As I promised in my other blog, here I have consolidated some of the errors that you may encounter while installing / upgrading / configuring / operating Cisco ECE. This document is written based on ECE 11.6, however most of these are true for higher versions as well; I will update specifically if there is any deviation between versions.
Firewall / Antivirus/ Memory Scanner
If you are running any antivirus, memory scanner or firewall on any of ECE servers, please stop or pause them at the time of installation or upgrading it to newer version or installing patches. These actions will fail while extracting files to ECE installation directory. You will see an error that says – “Failed to execute task: extract archives” and you’ll be asked to view installation/upgrade logs under ECE home directory; however, that would not give clear information as to why it failed.
Normally installation or upgrade of any ECE component will complete within 30 minutes if you are following Cisco hardware guide, but if you see your extraction process gets stuck then that’s a clear indication that one of your antivirus, firewall or memory scanner are blocking extraction. You will also see that these processes will start taking more memory than normal.
Mis-matched DB Version
Before you start installing ECE File server or ECE Core server, you need to have your SQL server ready. This SQL server should match the required SQL version, otherwise your File server / Core server installation will fail at the time of DB checks.
Here is rule of thumb:
If you are installing ECE 11.5 then you must have MSSQL 2014 SP1 Update 5 or higher
If you are installing ECE 12.5 then you must have MSSQL 2016 SP2 with CU2 or higher
Renaming ECE servers after installation
As of ECE 11.6 version, it is not possible to rename any ECE servers after ECE application is installed. It is also not possible to rebuild any of the servers except web server and DB server. This is mainly because eGMaster DB has a table (EGPL_DSM_HOST) which contains all server details and their functions.
Cisco Service does not start after installation
There can be several issues that can prevent Cisco service to start or it does not start properly. The easiest way to understand if Cisco Service has started properly, is to look at JAVA processes under task manager of Core server (if your deployment is collocated) or under Application server, Messaging server and Services server (if your deployment is distributed). If you want to know more about ECE’s collocated vs distributed environment, please look for section “Understanding Deployment Models” in below document:
Below are some of the most common factors to check if Cisco Service is not working properly on ECE:
- Cisco service must be set for “Delayed Start” in Windows Service center. Cisco service relies on certain Windows services, hence it must be started in Delayed mode to make sure all Windows services are started before Cisco service tries to start.
- Cisco service was not stopped properly last time, and hence there are residues of some java processes. To confirm this, go to Task Manager’s “Details” section and look for any java processes that are lingering around. Or look for any process that is running by the username which is used to run Cisco Service. If you find any, do a right click and click on “End process tree”.
- Cisco Service must be started in a specific order on ECE Distributed servers. You must follow below order to start Cisco Service on ECE distributed model and wait at each step for java process(es) to start and become stable:
- Messaging server (has one java process)
- Services server (has around 15 java processes)
- Application server (has one java process)
- I had a very precarious issue with one of our installs, where eGain support had to come in and change certain configuration files (bat files) under Services and Application servers in a distributed model. It’s a whole lot of things to cover here, if you would like to learn about it, please leave your comments and I will try to write it up in a separate document.
Retriever fails to start or very slow
If you are running large deployment with multiple retriever instances, then you may run into an issue where retrievers either does not start or they are very slow. While checking logs, you may see something like below:
com.egain.platform.util.Util <@> isApplicationServerJVM() <@> java.lang.OutOfMemoryError: Java heap space <@>
This indicates that ECE Application server / Core server is running out of Java heap memory. You need to increase java heap memory to resolve this issue.
Here’s the complete process to increase heap memory, approved by Cisco TAC:
- Login to partition 0 using SA user and find the exact name of the process you want to increase the heap size for.
- Stop the process prior to updating the database.
- Using SQL Management Studio, connect to the eGActiveDB with a user who has SELECT, INSERT, UPDATE, and DELETE rights.
- Select eGActiveDB and execute below query to verify current custom allocation (if any):
SELECT * FROM EGPL_CONFIG_PROPERTY WHERE NAME LIKE ‘JVM%’ - Execute the following query to insert a new value:
INSERT INTO EGPL_CONFIG_PROPERTY VALUES (‘egpl_dsm.xml’, ‘JVMParams.<exact name of process>’, ‘<heap size value>’, ‘<description>’) - If a value is present, then use the following query instead:
UPDATE EGPL_CONFIG_PROPERTY SET VALUE = ‘<new heap size>’ WHERE ‘NAME = ‘JVMParams.<exact name of process>’ - Use the query from step 4 to validate that the values now reflect what is desired.
- Start the process from partition 0, then start the respective instances.
The following query shows an example of increasing the rx-process to 512m:
INSERT INTO EGPL_CONFIG_PROPERTY VALUES(‘egpl_dsm.xml’,’JVMParams.rx-process’,’-Xmx512m’,’Custom heap size for RX process’)
OAuth 2.0 related issues
If you have not yet migrated to OAuth or configuring new ECE and want to know how to setup OAuth with ECE, please refer my blog here to learn more.
URL error while generating token:
When you try to generate Token from ECE Account, you get below error in browser:
Message: AADSTS90102: ‘redirect_uri’ value must be a valid absolute URI.
- Make sure your external ECE URL configured in Azure Application is accessible directly from the Internet.
Unable to add email address in ECE OAuth account:
You get error when you try to add email address as alias in ECE OAuth account. Retriever logs show below:
2022-05-12 20:15:23.139 GMT+0000 <@> ERROR <@> [35786:default task-1028] <@> ProcessId:1532 <@> PID:1 <@> UID:1540 <@> HttpSessionId:P_YPLVdB4wvF2jsUcwf16S72 <@> com.egain.mail.module.email.JavaMailConnection <@> connectInbound(CallerContext callerContext, boolean retry) <@> I18N_EGPL_RETRIEVER-AUTHENTICATION_FAILED_EXCEPTION <@>
javax.mail.AuthenticationFailedException: Authentication failure: unknown user name or bad password.
- First check that you have generated your Authentication token properly.
- If you are using AD Service Account to delegate authentication token for all email addresses used in ECE, then make sure that AD service account has proper permissions given on all email addresses. Refer my blog to learn more about these permissions.
- Third check that you are following correct steps to add email address properly.
Scheduled reports come out blank:
This is ECE 11.6 version specific bug – https://bst.cloudapps.cisco.com/bugsearch/bug/CSCwd61276 – where scheduled reports do not contain PDF attachment with data.
You need to install ECE 11.6(1) ES12 ET1 to resolve this issue.
https://software.cisco.com/download/home/286311237/type/286310764/release/11.6(1)_ES12_ET1
Import ECE Stock reports in CUIC
If you are running ECE 11.6 and trying to import ECE Stock reports in CUIC, then you should import ECE 12.0 templates, rather than ECE 11.6 templates. These templates have problem with Agent Work Summary report definition and they will not be successful.
Download ECE 12.0 CUIC templates from here. You will need CCO ID.
https://software.cisco.com/download/home/282163829/type/284697222/release/12.0(1)
If you are looking for more user specific ECE issues, then please refer my 2nd troubleshooting document here. Or if you have other specific question, then please drop in comment.