Upgrade Guide
This chapter outlines the steps required for a product upgrade installation in the Salesforce Cloud and on the Finesse server.
b+s Connects for Salesforce uses the Semantic Versioning method to name its releases. Based on its definition:
Given a version number MAJOR.MINOR.PATCH:
- MAJOR version indicates that the release contains incompatible API changes
- MINOR version indicates that the release adds functionality in a backwards compatible manner
- PATCH version indicates that the release contains backwards compatible bug fixes
Upgrade steps are described here with fewer details because a familiarity with the normal installation procedure is assumed.
Installing the upgrade during your call center off hours, when all agents are logged out is recommended. However, if the call center is open 24/7, please refer to the section Updating a Finesse Hosted 24/7 Operating Call Center.
Please read this entire section prior to starting any upgrade
Upgrade paths
The following upgrade paths are currently supported
Upgrade installation to the latest version
Please refer to section Manual installation via AppExchange or direct link for more detailed information on where to get the installation link from and how to start the installation; an upgrade is processed in the same way as an installation.
Patch upgrade to specific version
When performing a patch upgrade, you can still follow the same steps as in the Upgrade installation to the latest version section, with the difference being that the installation link will be for the patch version you wish to install. Please open a case with our b+s Customer Service to retrieve the required patch installation link.
Quick upgrade guide
- Get the installation link from b+s Customer Service for the required patch
- Login to the Salesforce instance you wish to apply the patch to
- Access the installation link from a new tab
- Select Install for Admins Only or Install for All Users depending on the initial installation
- Click Install
Once the installation is complete, you will see the new version displayed in the Installed Packages version and in the b+s Connects for Salesforce Softphone.
User Layout update after 5.3 version release
In version 5.3 of the b+s Connects for Salesforce package, the extension field was replaced in the User Layout. Please check the 5.3 Version of the New Configuration Keys to adjust your User Layout to the new field.
Port updates after 5.5 version release
In version 5.5 of the b+s Connects for Salesforce package, the port logic was changed to prioritize the newer Finesse server version connections. Please check the Default ports used by Connects Finesse Gadget to adapt your network configuration to the new requirements.
Required manual actions after package upgrade as per 5.3 release
As of version 5.3 of the b+s Connects for Salesforce package, the field Show State Change Time (located in the Realtime View Settings section), is automatically defaulted to false after install and upgrade.
Make sure to manually re-enable the field if needed.
This only relates to package upgrades from versions earlier than 5.3.
Required manual actions after package upgrade as per 5.5 release
Warning! This only relates to package upgrades to version 5.5 (and newer) when upgrading from older versions prior to version 5.5.
In order to considerably reduce blocking errors during the package upgrade, which are complex to debug and fix, the DML operations related to a standard object used by the package (User) have been removed from the upgrade script and must now be performed manually.
The following script copies the Agent extension from the old field to a new one in the User object (reference), only if the new field is still empty.
Open the Salesforce Developer Console, click Debug | Open Execute Anonymous Window (or press CTRL+E), and run the following code:
List<User> usersToUpdate = new List<User>();
// Retrieve active Users with a Agent Phone Extension set
for (User u : [SELECT cnx__Agent_Phone_Extension__c, cnx__Agent_Phone_Extension_v2__c FROM User
WHERE cnx__Agent_Phone_Extension__c !='' AND IsActive=true]) {
String oldFieldValue = u.cnx__Agent_Phone_Extension__c;
String newFieldValue = u.cnx__Agent_Phone_Extension_v2__c ;
// Only copy the value from the old to the new field if the new field is still empty
if (newFieldValue == null || newFieldValue == '') {
u.cnx__Agent_Phone_Extension_v2__c = oldFieldValue;
usersToUpdate.add(u);
}
}
update usersToUpdate;
Troubleshooting
Various errors could be thrown when running the code above, mostly due to limits or triggers hitting non-updatable Users.
Limits reached
- Export all
cnx__Agent_Phone_Extension__cvalues to a csv file using the preferred Export tool - In the csv, copy the Extension value to the new
cnx__Agent_Phone_Extension_v2__cfield and run the update making sure not to reach the limits imposed by your org - Delete the value from the old field (
cnx__Agent_Phone_Extension__c) for the previously updated Users - Repeat until the following query results in 0 rows:
SELECT Id FROM User WHERE cnx__Agent_Phone_Extension__c !='' AND IsActive=true
Any error generated from the aforementioned process, if not directly returned by the chosen Import/Export tool, can be caught by activating the Debug Logs in Salesforce (ref).
Errors related to the Shield Platform Encryption
if the Shield Platform Encryption with Encryption for custom fields in Managed Packages has been activated and at least one of User object's fields is encrypted (Agent_Phone_Extensionc and/or Agent_Phone_Extension_v2c), the migration of the values from Agent_Phone_Extensionc to Agent_Phone_Extension_v2c may generate errors, since the fields' content is not readable. Consider to temporarily deactivate the Encryption Shield while running the aforementioned script if error occurs.
Upgrade installation from 4.x to the latest version
With the b+s Connects for Salesforce 5.0 release, the configuration method has changed and improved.
The existing Call Center settings have now split into a minimal Call Center set and a b+s Configurations custom Object.
Split configuration to minimal Call Center and b+s Configuration Object
All users can use the same Call Center and then make further configuration customizations in the new b+s Configuration entity.
The new b+s Configuration Object with custom configuration wizard
The new minimalistic Call Center that can be assigned to all users
Quick upgrade guide
- Install the new b+s 5.x package
- New V9 Call Center is now available (do not map this Call Center to agents yet)
- Assign the included Permission Sets
- b+s Configuration Editor to users who configure b+s Configurations
- b+s Connects Agent to users who use the b+s Connects Softphone
- b+s Connects Supervisor in addition to the "b+s Connects Agent" Permission Set to users who work as supervisors
- Open App b+s Configurations to view and edit the b+s Configurations custom object
- Adapt the default configuration – a new configuration is needed per Call Center profile
- The parameters will need to be manually configured. (no automation / export / import is available)
- Assign the SF users to the current configuration
- Map selected users with the V9 Call Center, created in step 1.a (all have the same SF Call Center)
- Refresh the agent pages
- Continue working with the new b+s Connects for Salesforce version.
Install the New Connects For Cisco Contact Center Package
Before Installing the Package
The package will try to install a new Call Center Settings entry with the internal name "CNXforCCEV009" and will skip that step without any warning if a Call Center configuration with the same internal name already exists.
Make sure that you do not have a Call Center Settings entry with internal name CNXforCCEV009:
- Click Setup | Feature Settings | Service | Call Center | Call Centers
- Open any existing entry and check the field InternalName
- Rename any entry if needed
Install the Package
The latest stable release of the Cisco Contact Center Package is available in AppExchange: https://appexchange.salesforce.com/listingDetail?listingId=a0N300000059NTvEAM
To install the package in a Sandbox, the credentials used in the Salesforce login page must correspond to the Sandbox Org in which the Package must be installed.
Patch releases are provided directly or on request by Bucher + Suter. To install a patch release in a Sandbox environment, replace the "login.salesforce.com" part of the URL with "test.salesforce.com".
To install the package:
- Open AppExchange or the package link provided to start the installation
- Login to the Salesforce organization where the package will be installed
- In the installation wizard, choose the security option "Install for Admins Only" (1) and click Install (2).
Note: It will be necessary to decide which users get certain permissions to the objects and components that come with the b+s Connects for Cisco Contact Center package. In addition, granting them these permissions (which is aided by the Permission Sets that come with the b+s Connects for Cisco Contact Center package) is also needed.
Package installation wizard – Welcome screen
We do not recommend choosing the "Install for All Users" option, as this will grant all permissions (read, create, edit and delete) on the package components and objects to any user who uses a custom User Profile. As an example, these permissions would also enable these users to edit the Configuration of the b+s Connects Gadget or to access the supervisor page.
Due to a limitation in Lightning dashboards, it is possible from for an upgrade from version 5.5 to fail. Please create a permission set with the 'Change Dashboard Colors' permission and assign it to the user installing the release. For more information see https://help.salesforce.com/s/articleView?id=000349418&type=1
Once the installation is complete:
- To use a Finesse hosted deployment, use the link
Connects Gadget (to copy on Finesse server)to download the Connects Finesse Gadget. - For SSO deployments, download the Finesse SSO Frame with the
Finesse SSO Frame (to copy on Finesse server)link.
- To use a Finesse hosted deployment, use the link
Click Done to exit the installation wizard
Package installation wizard – Completion screen
If the installation fails, please contact the b+s Support Center reporting the errors encountered in the most detailed way. If possible, also take a screenshot of the page where the error occurred.
The Visualforce page of the Connects gadget will be automatically updated for all the agents that are configured for this deployment. Those agents will be forcefully logged out after the next reload of the Connects gadget. This only happens once right after the update and the agents can continue working normally right after they log in again.
Copy Your Settings Values to the new b+s Configuration entry
With this release the new b+s Configuration Object was introduced.
In order to have access to the b+s Configuration object add the Permission Set b+s Configuration Editor to the Admin User.
A new b+s Configuration was automatically created after the installation. Create a new b+s Configuration entity for each existing Call Center as described in chapter 4.4. Copy the settings from your old Call Center settings to the new b+s Configuration and assign the agents to the b+s Configuration. For all agents that are not directly assigned to a b+s Configuration entity the default b+s Configuration is used.
The agents switch to the new configuration after changing the assigned Call Center, not the b+s Configuration.
Migrate Call Center of previous release to b+s Configurations
Assign users to b+s Configurations
Switch the Agents to the New Version
You can first switch a small number of agents to the new version to test if everything works as expected and move the others later.
The new Call Center has to be assigned to all Agents. The different configurations are assigned in the b+s Configuration Object.
It is possible to manually move the agents over to the new installation by assigning them each to the new Call Center configuration.
Assign users to new Call Center (V9)
Finesse Hosted Deployment
When the new version of the Connects Finesse Gadget is installed on the Finesse Server and the new Call Center Settings entry is prepared and points to the new version of the Connects Finesse Gadget on Finesse server, you can easily switch the agents to the new version simply by reassigning them to the new Call Center configuration.
If you switch agents to the new version during business hours while they are still logged in, these agents will be logged out from the gadget when the page is reloaded next time and the login window will appear. They will have to re-login to continue working.
Note for Updating a Finesse Hosted 24/7 Operating Call Center
It is possible to upgrade a 24/7 operating call center using the following protocol:
- Obtain a copy of the new Connects Finesse Gadget to install on Finesse Server either by installing the package before in a sandbox and download it from the "Configure" page of the package or request it from b+s Support Center.
- Install the new version of the Connects Gadget on all Finesse servers in a new subfolder named V_MAJOR_MINOR_PATCH (where MAJOR, MINOR and PATCH correspond to the latest version installed)
- Update the package in the production Salesforce environment.
- Edit the new Call Center Settings entry (finesse hosted only)
- Create a new b+s Configuration and copy the values form the old Call Center Settings
- Assign the Users to the new b+s Configuration
- Reassign the test agents to the new Call Center and test that everything works as expected
- Reassign the real agents to the new Call CenterOtherwise, they will have to login again after page reload.
- It is recommended reassigning agents during their individual off hours.
The new version package is backward compatible with the Connects Finesse Gadget web application of 4.x release only during the upgrade. Mixed versions working mode will not be supported.
The agents can continue working with the old version of the gadget until they are switched to the new version to complete the upgrade.
Install the new b+s Connects for Salesforce on the Finesse Servers
For CRM hosted deployments, skip this section.
Download Connects Finesse Gadget web application Resources
Download the new version of the Connects Finesse Gadget from the Configure page of the Installed Package Connects for Cisco Contact Center with the new Version Number.
Please see section Download the Connects Finesse Gadget Web Application Resources application for a detailed description on how to download the Gadget.
Upload the Connects Finesse Gadget to Finesse Server
In order to prevent problems with cached web pages from the old version it is essential that you use a different URL for the new version of the gadget resources on the Finesse server by adding a version subfolder.
This also allows the old and new versions of the gadget to be used in parallel and makes it easy to migrate some test agents to the new version first and then later the remaining agents.
Upload the content of the ConnectsGadget.zip using an FTP client to the Finesse servers A/B into the folder: <Finesse Server A/B>/3rdpartygadget/files/Connects/V_MAJOR_MINOR_PATCH/
Please see section Upload Connects Finesse Gadget Resources on Finesse Server for a detailed description on how to upload the gadget to the Finesse servers.
Upload the Finesse SSO Frame to the Finesse Server (SSO deployment only)
Upload FinesseSSOFrame.html to both Finesse servers so that it is reachable at
https://<Finesse Server A/B>:<Port>/3rdpartygadget/files/Connects/V_MAJOR_MINOR_PATCH/FinesseSSOFrame.html
Configure the New Call Center Settings for Finesse Hosted
For CRM hosted deployments, skip this section.
After a successful upgrade of the package a newly added Call Center entry named "Connects for Cisco Contact Center V9" will be available.
It is necessary to configure this newly added "Connects for Cisco Contact Center V9" entry and reassign agents to this new entry.
It is mandatory to only use the new "Connects for Cisco Contact Center V9" entry (or copies of the new entry) for the new version of the product, as they have the latest updates.
For multiple Finesse servers or multiple different Call Center configurations open the settings entry and use the Clone button to make a copy of the entry.
To upgrade an existing deployment with the additional case routing feature, configure the deployment type in the b+s Configuration properly.
Please see Document "Case-Routing Add-on Installation Guide" [4] for more information.
Set Connects Gadget and Finesse URLs
Set the Gadget URLs in the new settings entry to the path where you installed the new version of the Gadget on Finesse servers
Example URL for a CCE Finesse hosted deployment:
Lightning: https://<Finesse Server A/B> /3rdpartygadget/files/Connects/ V_MAJOR_MINOR_PATCH/crm/Salesforce/connectsLightning.html
Classic: https://<Finesse Server A/B> /3rdpartygadget/files/Connects/ V_MAJOR_MINOR_PATCH/crm/Salesforce/connects.html
Example URL for a CCX Finesse hosted deployment:
Lightning: https://<Finesse Server A/B>:8445 /3rdpartygadget/files/Connects/ V_MAJOR_MINOR_PATCH/crm/Salesforce/connectsLightning.html
Classic: https://<Finesse Server A/B>:8445 /3rdpartygadget/files/Connects/ V_MAJOR_MINOR_PATCH/crm/Salesforce/connects.html
New or Changed Configuration Keys
Removed Configuration Keys
Omni Channel Federation - Chats To Set Voice Not Ready
This option is deprecated. You can still find this setting embedded in the Set Voice Channel in Not Ready Type new configuration key when selecting Chats (Deprecated).
New Configuration Keys
Omni Channel Federation - Set Voice Channel in Not Ready Type
This setting allows the administrator to choose which threshold or primary capacity should be taken into consideration to set the Voice Channel in Not Ready state. This new key needs to be configured together with Units To Set Voice Not Ready or Percentage To Set Voice Not Ready and Not Ready Reason Code
Omni Channel Federation - Units To Set Voice Not Ready
When Primary Capacity Units is selected in the Set Voice Channel in Not Ready Type configuration, this option becomes available. The number will indicate the amount of units that will trigger the threshold to change the voice channel state to not ready.
Omni Channel Federation - Percentage To Set Voice Not Ready
When Primary Capacity Percentage is selected in the Set Voice Channel in Not Ready Type configuration, this option becomes available. The number will indicate the amount of percentage that will trigger the threshold to change the voice channel state to not ready.
Updated Configuration Keys
WCCAI Tenant
Changed default value from us1 to empty.
Upgrade Legacy Named Credential for Calabrio Cloud
Starting with b+s Connects for Salesforce v.5.9, the Legacy Named Credentials are no longer supported. All current legacy Legacy Named Credentials need to be deleted and replaced with the new Named Credentials.
Refer to Calabrio Cloud Salesforce Named Credentials for a step-by-step tutorial on how to set up new Named Credentials.
Downgrade to an older version of the solution
It is not possible to downgrade an installed package of an application in the Salesforce environment to an earlier version of the package. Either upgrade to a newer version or uninstall the package completely and then reinstall the old version.
To uninstall the new package and reinstall the old package, first consider the following:
- The package cannot be uninstalled if any customizations in the Salesforce environment dependent on the installed package have been made. These customizations will also be removed.
- Users that are assigned to the package and the Call Center have to be reassigned after reinstallation of the old version.
- The Call Center configuration needs to be reconfigured after reinstallation of the old version.
- All information stored in fields provided by the "Connects for Call Center" package is lost
- User record for automatic sign in
- Task record for call activities (e.g. CTI Info field)
An uninstall and new install of the Salesforce package resets license status to trial. The license must be activated by b+s and must then be reassigned to the users.