CX Voice upgrade Guide

Add a tenant using the Domain utility. Follow this guide to deploy the domain utility and to add a tenant.

• SSH into the Media Server.

  • Use command

    CODE

    ssh username@server-ip

  • Enter user password and press ENTER.

  • Use command

    CODE

    su

  • Enter root password and press ENTER.

• Confirm git is installed, and install it if is not.

• Make a directory name as upgrade-5.0 anywhere.

• CODE

  mkdir upgrade-5.0

• Navigate to the newly created directory

• CODE

  cd upgrade-5.0

• Clone the Media Server scripts repository:

  CODE

  git clone -b TAG https://efcx:RecRpsuH34yqp56YRFUb@gitlab.expertflow.com/rtc/freeswitch-scripts.git

  • Where TAG is the 5.0

• Navigate to the cloned repository to access the files:

  CODE

  cd freeswitch-scripts

• Move the files ending in .lua  to the Media Server scripts folder:

• CODE

  mv *.lua /usr/share/freeswitch/scripts

• Move any custom IVR scripts to the Media Server scripts folder:

  CODE

  mv <custom-lua-IVR-script> /usr/share/freeswitch/scripts

• Move the ivr_prompts folder:

  CODE

  mv ivr_prompts/* /usr/share/freeswitch/sounds/ivr_prompts/

• Assign read-write permissions to the ivr_prompts and scripts folder:

  CODE

  chmod 777 -R /usr/share/freeswitch/sounds/ivr_prompts
  chmod 777 -R /usr/share/freeswitch/scripts

• Navigate to scripts directory

• CODE

  cd /usr/share/freeswitch/scripts

• Alter the file name of cx_env.lua to cx_env-{Domain-Name}-{DN}.lua where {Domain-Name} is the name of the Domain eg expertflow, or tenant1,  {DN} is the dialing number of the IVR (Set in the CxIvr Dialplan section below). This {DN} is already created with the name cx_env-{DN}.lua i.e cx_env-1884.lua.

  • e.g. for an IVR with a dialing number of 1555 and Domain Name is tenant1 the file would be named cx_env-tenant1-1555.lua.

  • Do the same for all the DN file already exists

    CODE

    mv cx_env.lua cx_env-tenant1-1555.lua

• Configuration

1. Open cx_env-{Domain-Name}-{DN}.lua :

   CODE

   vi /usr/share/freeswitch/scripts/cx_env-{Domain-Name}-{DN}.lua

   CODE

   local config = {}
   local domain = session:getVariable("domain_name")
   local cxFqdn = ""
   if domain == "expertflow" then
       cxFqdn = "https://efcx4-voice.expertflow.com"  -- set Default Domain here 
   else
       cxFqdn = "https://" .. domain .. ".expertflow.com"  -- set Tenant based Domian here
   end
   config = {
       -- Set to NAME or ID depending on whether queue field contains name or ID of queue
       queueType = 'NAME',
       -- Name or ID of queue to reserve agents from
       queue = 'Test Voice Queue',
       -- NOTE: Keeping queue and queueType as '' will cause CX to use the default queue set in the CX Voice channel
       -- queue = '',
       -- queueType = '',
       -- FQDN of EF CX
       cxFqdn = cxFqdn,
       -- API of voice connector for reserving an agent
       voiceConnectorApi = "http://VC-IP:PORT",
       -- Path of folder containing sound files that play during the IVR menu, DO NOT CHANGE
       ivr_prompts_folder = "/usr/share/freeswitch/sounds/ivr_prompts/",
       auth_enabled = false,
       auth_realm = "expertflow",
       client_secret = "1234",
       client_id = "cim",
       username = "voice_auth",
       password = "1234"
   }
   return config

2. Press the "I" key to enter editing mode.

3. The cxFqdn is dynamic in case of MTT, and for Single Tenant its value is hardcoded on line 7.

   1. Single Tenant: set cxFqdn as https://efcx4-voice.expertflow.com , replace it with actual FQDN.

   2. MTT: cxFqdn is set dymanically by fetching the domain value form Channel Variables. The Root Domain need to be udpated. expertflow.com replace it with actual Domain

4. The queueType field can contain one of two values:

   1. 'NAME'

   2. ''

5. The queue field can contain one of two types of values, based on what the queueType field above contains:

   1. Name of the Agent Queue e.g. Support Queue (If queueType contains 'NAME') This name can be obtained from Unified Admin from the Queues section.

   2. Empty string i.e. '' (If queueType contains '')

6. If queue and queueType are set to '' , then the call will be routed to the default queue set for the CX Voice channel in Unified Admin.

7. The voiceConnectorApi field will contain a URL in the following format:

   1. http://VC-IP:VC-PORT/request-agent

   2. Replace VC-IP and VC-PORT with IP address and port of the voice connector.

8. The ivr_prompts_folder field contains path to the ivr_prompts folder. Leave it at the default value.

9. AUTH_ENABLED: true or false depending on whether APISIX authentication is enabled in EFCX. The four settings below are set if this value is true.

10. API_USERNAME: The username created in Keycloak for API authentication.

    • On Keycloak create a user in the Expertflow realm.

    • Assign the admin and default roles, and have Email-Verified option enabled.

    • Assign a non-temporary password to this user as well.

11. API_PASS: The password for the above user created in Keycloak for API authentication

12. CLIENT_ID: Should always be cim.

13. CLIENT_SECRET: Found on Keycloak in the cim client.

14. Save and exit the file by pressing the Esc key, entering :wq and pressing ENTER.

15. Steps 16-21 below are optional, in case Post-Call-Survey is in use.

16. Open pcs1_env.lua:

    CODE

    vi /usr/share/freeswitch/scripts/pcs1_env.lua

    CODE

    local config = {}
    config = {
        formId = "form-id123",
        cxFqdn = "https://devops.expertflow.com",
        ivr_prompts_folder = "/usr/share/freeswitch/sounds/ivr_prompts/"
    }
    return config

17. Press the "I" key to enter editing mode.

18. The formId will contain the ID of the PCS Survey form created on Unified Admin (make sure that audio prompts were uploaded for each question).

19. The cxFqdn field contains the fully qualified domain name of the EFCX:

    1. Replace devops.expertflow.com with the EFCX domain name.

20. The ivr_prompts_folder field contains path to the ivr_prompts folder. Leave it at the default value.

21. Save and exit the file by pressing the Esc key, entering :wq and pressing ENTER.

22. Open vcApi.lua:

vi /usr/share/freeswitch/scripts/vcApi.lua

23. Search for fsIp and Replace fsIp = '192.168.1.161' with your actual Media Server Public IP

24. Save and exit the file by pressing the Esc key, entering :wq and pressing ENTER.

• Login to Media Server web interface. 

  • Open in browser: https://IP-addr, where IP-addr is the IP address of the Media Server.

• Add the username and password that was shown upon installation of Media Server and press LOGIN.

• Press the IP address in the top right and select the previously created Domain where all the extension were created before:

• Open the Extensions section under the Accounts tab.

• Open the extension one be one and scroll down to Domain and context.

• Change the context and domain name to your newly created Domain e.g expertflow, tenant1.

• All the Extension will start to appear in the newly created Domain. It can be check by selecting your newly created Domain and to Extensions.

• Login to Media Server web interface. 

  • Open in browser: https://IP-addr, where IP-addr is the IP address of the Media Server.

• Add the username and password that was shown upon installation of Media Server and press LOGIN.

• Press the IP address in the top right and select the Old Domain that was in use so far in the Domain creation section above:

• Open the Dialplan Manager section under the Dialplan tab.

• Open the Inbound IVR Dialplan could be named as CxIvr. This is the dialplan where DN is mentioned.

• Set the Context field to the value of the Domain set in the Domain creation section.

• Set the Domain field to the value of the Domain set in the Domain creation section.

In case of Multi Tenants, each Domain has it dedicated DN so set the Domain and Context accordingly.

In case of Single Tenant the Domain name and Context would be ‘expertflow’

• Save the changes by pressing SAVE button in top right corner.

• Do the same for the following Dialplan

  • WebRTC

  • Post Call Survey Dialplan (If using Post Call Survey other wise ignore it)

• Login to Media Server web interface. 

  • Open in browser: https://IP-addr, where IP-addr is the IP address of the Media Server.

• Add the username and password that was shown upon installation of Media Server and press LOGIN.

• Press the IP address in the top right and select the Domain created in the Domain creation section above:

• Open the Dialplan Manager section under the Dialplan tab.

• Open the Outbound IVR Dialplan.

• Set the Context field to the value of global.

• Set the Context field to the value of global.

• Save the changes by pressing SAVE button in top right corner.

• Do the same for the following Dialplan

  • Direct_Transfer Dialplan (CxQueue)

  • External Consult and Transfer Dialplan

  • Progressive Outbound Dialplan

  • Manual Outbound Dialplan

  • Custom Hangup Dialplan

  • Silent Monitoring Dialplan

  • Conference Dialplan

• Login to Media Server web interface. 

  • Open in browser: https://IP-addr, where IP-addr is the IP address of the Media Server.

• Add the username and password that was shown upon installation of Media Server and press LOGIN.

• Press the IP address in the top right and select the Existing Domain, which was in use, in the Domain creation section above:

• Open the Dialplan Manager section under the Dialplan tab.

• Find and open the user_record dialplan.

• Make sure to delete the lines present previously in Group 9 apart from the first one, and NOT in the table and image below.

• Add the following data to the table, such that the final version of Group 9 looks like the image below:

• Save the changes by pressing SAVE button in top right corner.

• Repeat this step for the newly created Domain as well.

• Login to Media Server web interface. 

  • Open in browser: https://IP-addr, where IP-addr is the IP address of the Media Server.

• Add the username and password that was shown upon installation of Media Server and press LOGIN.

• Press the in the top right and select the Domain created in the Domain creation section above:

• Once the domain is selected then click on the dilaplan menu and on the drop down section click the dialplan manager. once the dial plan are open search for the voicemail dilaplan

  

• Cline on the voicemail dialplan is opened like below, then turned off the Enabled button to make the dialplan false/turnoff

  

• SSH into the Debian server.

  • Use command:

    • CODE

      ssh username@server-ip

  • Enter the ssh password and press Enter.

  • Use command:

    • CODE

      su

  • Enter the root user's password

Container deployment

The voice connector is deployed as a docker image.

• Navigate to the existing Voice connector directory

• CODE

  cd voice-connector

• Stop the previously running container

• CODE

  docker compose down

• Open the file docker-compose.yml.

  • CODE

    vi docker-compose.yml

• Enter editing mode with the 'I' or 'Insert' keys.

  • Replace the previous the tag with 5.0

    CODE

    version: "3.8"
    services:
      voice-connector:
        image: gitimages.expertflow.com/freeswitch/ecx_generic_connector:<TAG>
        deploy:
        
        ...
        ...

• Save the file and exit by :

  • Press the Esc key.

  • Enter the phrase :wq to save and exit.

• Open the env.txt

  • CODE

    vi env.txt

• Enter editing mode with the 'I' or 'Insert' keys.

• Add these environment variables into the file env.txt : 

  CODE

  AUTH_ENABLED=true
  API_USERNAME=voice_auth
  API_PASS=pass
  CLIENT_ID=cim
  CLIENT_SECRET=secret
  ROOT_DOMAIN=expertflow
  ESL_DEFAULT_DOMAIN=192.168.1.17

  • AUTH_ENABLED: true or false depending on whether APISIX authentication is enabled in EFCX. The four settings below are set if this value is true.

  • API_USERNAME: The username created in Keycloak for API authentication.

    • On Keycloak create a user in the Expertflow realm.

    • Assign the admin and default roles, and have Email-Verified option enabled.

    • Assign a non-temporary password to this user as well.

  • API_PASS: The password for the above user created in Keycloak for API authentication

  • CLIENT_ID: Should always be cim.

  • CLIENT_SECRET: Found on Keycloak in the cim client.

  • ROOT_DOMAIN: Keep it as “expertflow” as realm name will be expertflow in Migration.

  • ESL_DEFAULT_DOMAIN: Media Server IP through which ESL connection can be established

• Run the command:

  • CODE

    docker login gitimages.expertflow.com

  • Enter your username and password as prompted (make sure that you were granted access to the repository).

• Within the folder run the command:

  • CODE

    docker compose up -d

• Confirm that the new docker container is running by using the command:

  • CODE

    docker ps

• Confirm that the container is running correctly by opening the logs with command:

  • CODE

    docker logs -f containerID

• If there are multiple Voice Connectors running update all of them if needed.

For the Voice Connector to be able to access the Freeswitch ESL for communicating with Media Server, their IP address must be added to the ACL.

• Login to Media Server web interface. 

  • Open in browser: https://IP-addr, where IP-addr is the IP address of the Media Server.

• Add the username and password that was shown upon installation of Media Server and press LOGIN.

• Press the IP address in the top right and select the Domain created in the Domain creation section above:

• Open the Access Control List from the Advanced tab.

• Open ACL by clicking the name esl

• In the esl:

  • It is required to add the IP addresses of the Voice Connector docker containers.

    • On the Voice connector servers, use the command docker ps to list the containers.

• Run the command:

  • CODE

    docker inspect containerID

  • Scroll down to the Networks object and find the Gateway and IPAddress fields.

• Verify if the value of Gateway and IPAddress is added in esl ACL.

• If it is already added ignore the remaining steps.

• If it is not added follow next steps to add it in esl ACL.

• Copy these two addresses to the esl ACL.

• Click the Save button and go to the SIP Status with from the Status tab.

• Click the Reload ACL button on the top right.