Troubleshooting

The topics in this section contain the steps for solving problems identified in SoftExpert Suite.

Requirements check

Since version 2.0.5, SoftExpert Suite has a requirements checker. This resource is a feature that is executed during the SoftExpert Suite startup and aims to ensure that the server meets all the system usage requirements. If a requirement does not meet the system usage, the checker will display a message to indicate the configuration that needs to be resolved.

See below some settings that may be requested for starting the SoftExpert Suite service:

Setting the time zone in Java

By default, the time zone used in Java is the same as that configured in the operating system. In order for the application to be started with a time zone different from that used in the operating system, this information must be passed on to Java at system startup using the user.timezone attribute ▪ Edit the JAVA_OPTS variable; if it does not exist, set it with the value -Duser.timezone=America/Sao_Paulo.

The time zone used in the example is the official Brazilian time zone; the identifier for other time zones can be found at: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones(Accessed on Sep/08/2016).

Adjusting daylight saving time

If the system displays a message of divergence regarding the daylight saving time configuration between Java and PHP, the problem may be in the version of the Java time zone database. To update the database, follow these steps:

▪ Download the "ZIUpdater Time Zone Tool" app.

▪ Run the application with the same Java virtual machine used by SoftExpert Suite with the "java -jar ziupdater-1.0.1.2.jar" command line.

info

If the current directory is not the same as the one where ziupdater is located, use the full path to the ziupdater file.

info

To compare the versions of the Java and application time zone databases, run the "java -jar ziupdater-1.0.1.2.jar -V" command.

Setting the time zone in PHP

The installer will automatically create the suite.env file containing the "America/Sao_Paulo" default time zone. However, to change the time zone that will be used by PHP, the suite.env file must be edited (which is in /usr/local/se/suite.env); otherwise the default will be "America/Sao_Paulo".

If the file does not exist, simply create it.

To edit the time zone, open the file for editing and set the TZ variable in accordance with your time zone:

TZ=America/Chicago

The time zone used in the example is the official Brazilian time zone; the identifier for other time zones can be found at: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Troubleshooting Java problems

System	Parameter	Description
GENERAL	HD	"HD has free space of AVAILABLE DISK SPACE, when it should be at least 5GB."

Solution
Free up physical space on the machine.

System	Parameter	Description
GENERAL	JavaVersion	"The installed Java version is JAVA VERSION, when it should be 1.8."

Solution
Remove the Java version and install the correct version.

System	Parameter	Description
GENERAL	TomcatMemory	"The Apache Tomcat server is configured to use up to CONFIGURED_MEMORY MB of memory. At least 1024 MB of memory is required. Check in the system installation guide how to set this configuration."

Solution

For GNU/Linux environments, see the Memory check for Apache Tomcat section.

System	Parameter	Description
LINUX	java.awt.headless	"The Java AWT library, used to render charts and reports, is not enabled on the application server. To enable it, change the value of the "java.awt.headless" parameter to "true."

Solution

Edit the SESUITE_HOME/apps/tomcat/bin/setenv.sh file and check the "export JAVA_OPTS=" line, which must contain the value true for the -Djava.awt.headless=true parameter.

Troubleshooting template problems

System	Parameter	Description
GENERAL	...web\include\template	The FILE_NAME template is not a template in JSON format.

Solution

Contact SoftExpert.

Troubleshooting application server problems

System	Parameter	Description
GENERAL	GET/POST/PUT/DELETE	The application server is configured to block HTTP requests with the METHOD method

Solution

Release requests to the application server with the required method.

Troubleshooting NODE problems

Database port configuration

During CHECKSYSTEM (process that validates the system at startup), the export service is validated. One of the most common problems that occurs with this service is having a specific port defined that is not accessible by the service. Therefore, we recommend updating the database directly, thus defining an automatic port (value 0) or a specific one to resolve this situation.

Change through the database:

UPDATE bi2config SET nrportexport = 0 --Port number

WHERE oid = 1;

Node.js checkpoints

• Make sure that the installed node version is 8.9.1.

• All libraries must be installed during the installation process.

• The TEMP path needs all the correct permissions.

• The server must meet memory requirements; otherwise, slow exports or failures may be generated.

• Make sure the server has the fonts used in the system installed; the server must have at least the Arial font available.

• If there is an antivirus service installed on the server, make sure to add SoftExpert Suite to a list of Internet scanning exceptions using the website blocking feature.

Indexing server

The objective of the indexing server is to extract data from SoftExpert Suite records and files for indexing. Indexes are used in some system queries, in addition to the general query. This service works in parallel with the system; when SoftExpert Suite starts up, the indexing service starts up as well.

The indexing server is made up of two important services for its correct functioning, namely:

Atlas

Atlas is the name of the internal engine developed by SoftExpert that encapsulates the Elasticsearch engine and provides services to ensure better communication with SoftExpert Suite. This service is used in general and component queries.

Elasticsearch

Elasticsearch is a powerful search and indexing tool for textual searches (Full-Text Search). One of its main qualities is its high performance in the search, in addition to being adaptable to systems with Load Balance. For more information, see the engine website.

Here are the steps to check whether the service is running:

How do I know if Atlas and Elasticsearch have started?

When an environment with Elasticsearch support is deployed, if the engine has been successfully deployed, it must create the atlas.pid and elasticsearch.pid files (or overwrite them, if any) in the ‘SESUITE_HOME\system\tools\indexer’ directory.

Atlas/Elasticsearch is not live. What should I do?

If you have deployed SoftExpert Suite and, even so, the Elasticsearch or Atlas service has not run along with it, first check if the configurations of both the environment and the SEFTSSETTINGS table are in accordance with what is expected. If the configuration is correct, or if the system administrator has doubts about these settings, SoftExpert's support team must be contacted to analyze the situation.

In some cases, this service may not work properly. Here is a list of possible causes and their solutions:

Port blocked on the FIREWALL

1. To check the port that is being used by the Atlas and Elasticsearch services, run the following query:

#Port used by the Atlas service

SELECT NRENGINEESPORT FROM SEFTSSETTINGS

#Port used by the Elasticsearch

SELECT NRESPORT FROM SEFTSSETTINGS

2. Check if there is any firewall configuration on the server blocking the port of the NRENGINEESPORT parameter, or of the NRESPORT parameter. After unlocking the ports, you will need to restart the system and check if the indexing service is running.

Port being used in another service

1. Run the command below to check which port is being used.

Example

#Ports used by the index server (Atlas/Elasticsearch)

SELECT NRESPORT, NRENGINEESPORT FROM SEFTSSETTINGS

2. Check if there is any other service that is using the port of the NRENGINEESPORT and NRESPORT parameters. If there is, change to an available port.

info

IMPORTANT! Never run commands to change ports or other parameters in the SEFTSSETTINGS table without a prior analysis of the impact and without, first, consulting with SoftExpert's support team.

System version

The system checks package versioning in order to keep SoftExpert Suite stable. Incompatibilities between the versions of installed/updated packages may be found. See below the solution to stabilize SoftExpert Suite:

1. Access the SoftExpert Configurator directory:

# cd /usr/local/se/tools/configurator

2. Run the following command to update and reconfigure the database connection data:

# bash run.sh

3. After equalizing, restart the system.

Memory check for Apache Tomcat

1. Access the folderbin, located inside the directory where Tomcat is installed.

# cd /usr/local/se/apps/tomcat/bin

2. Open the setenv.sh file for editing:

# vi setenv.sh

3. In the file, look for the "set JAVA_OPTS" line. If it exists, check whether the values assigned to the "-XX:MaxPermSize" and "-Xmx" variables have the minimum value of 1024m. If the line does not exist, or the variables are not configured correctly, add this line, leaving it similar to:

set JAVA_OPTS=  -Xmx1024m -XX:MaxPermSize=1024m

info

The values specified above are the minimum necessary for SoftExpert Suite to work correctly. If needed, assign values higher than 1024m to these variables.

4. Save and close the file

:wq!

Increase the number of concurrent PHP processes

If you need to raise the limit of simultaneous PHP processes, due to a more intense use, follow the steps below:

1. Access the file:

# vi /usr/local/se/apps/php/etc/pool.d/www0.conf

2. Change the 'pm.max_children' parameter to the desired value, for example:

pm.max_children=80 # (In this case, there will be a maximum of 80 simultaneous processes)

info

The maximum value must be based on the ratio between the amount of available ram memory on the machine and the average amount of memory consumed in each process. This second piece of information can be obtained by checking the RSS column of the command output:

ps -ylC php-fpm --sort:rss

Single Sign-On

To anticipate possible problems in the process of synchronizing and authenticating users in a domain, it is possible to test the domain configuration in the system authentication configuration (CM008), "Directory integration > Domains" section, when creating or editing a record . This procedure will test communication between the SoftExpert Suite server and the authentication and directory servers specified in the configuration. The protocols tested are LDAP, using the connection string, the entered user name and password, and communication with the domain address and port NTLMv2, for authentication via the NTLMv2 protocol.

Usually, failure during the connection test occurs if there are errors in the domain configuration or issues in the network connections between the SoftExpert Suite server and the servers that host the directory and authentication services. Therefore, we recommend using tools for connection diagnostics, or asking the network administrator for assistance to check addresses and ports used in communication.

Possible returns from the connection test:

▪ Message on error when connecting to the domain controller: The SoftExpert Suite server was unable to establish a connection via the LDAP protocol using the URL entered in the "Connection String" field. Check that the field is filled in correctly; if a port was not specified in the URL itself, check that the server is accepting connections on the default LDAP port 389, or on ports 636 and/or 3269, the default ones for LDAPS, or contact the directory service administrator to check service availability.

▪ Alert message stating that the connection via NTMv2 has failed: The SoftExpert Suite server was unable to establish a connection to the domain address and port specified in the configuration. Check that the respective fields ("Domain Address" and "NTLMv2 Port") are correct, and that the destination server is accepting connections on the specified port. If it is not, check your firewall rules or contact your network administrator. Note: If you do not intend to use the NTLMv2 authentication protocol, this alert can be ignored.

▪ Error message stating that the user was not found or the password is incorrect: Communication with the directory service occurred without problems, but the user and password entered in the "User" and/or "Password" fields are incorrect. This user refers to a user registered in the directory service; therefore, check whether the name and password match the information recorded in the service. Remember that, in the "User" field, the user's name must be entered, not the login.

▪ Alert message stating that authentication via NTMLv2 has failed: In this case, the "User login" (example: user.test@domain.local) and/or the "Password" entered are incorrect. The user in question is also a user registered in the directory service, so you just need to check whether the information is correct. Note: If you do not intend to use the NTLMv2 authentication protocol, this alert can be ignored.

Outlook configuration

If there is a problem sending attachments, that is, a recipient is not receiving e-mail attachments, this is possibly due to a Microsoft Outlook setting. This section will present some settings that can be defined in Outlook to solve this problem.

Problem cause

This is a common problem that occurs because of Outlook, when a message is sent in RTF (Rich Text Format) format and is not converted correctly into HTML or Plain Text.

Solutions

Submission using HTML or Plain Text format

One possible issue is that you are sending the attachment in RTF format and the message is not being converted correctly to HTML or plain text. In this case, follow the steps below to solve the problem.

1. In Outlook, access the File > Options menu:

2. On the Outlook options screen, select the Mail menu. Then, in the Compose messages section, select the "HTML" or "Plain Text" option in the Compose messages in this format: field.

3. Still in the Mail menu of the Outlook options screen, locate the Message format section. Then, make sure the When sending messages in Rich Text format to Internet recipients field is configured with the "Convert to HTML format" option or with the "Convert to Plain Text format" option.

4. Click on OK to save the changes.

Replying to an e-mail

If you need to reply to a received e-mail, in order to prevent the problem of the attachment disappearing with the reply, change the message format to HTML. To do this, first, open the e-mail on reply mode. Then, set the following configurations, which depend on your Outlook version:

If your Outlook version is 2003

i. Select the Formatting tab.

ii. Select the HTML option.

If your Outlook version is 2007

i. Select the Options tab.

ii. Select the HTML option.

If your Outlook version is 2010, 2013 or 2016

i. Select the *Format text** tab.

ii. Select the HTML option.

Docker certificates

Some SoftExpert Suite services are currently run on docker containers. These containers use docker images created by SoftExpert and stored in Docker Hub.

When the SoftExpert Suite service is started and these images are pulled, if an ERROR: Get https://registry-1.docker.io/v2/: x509: certificate signed by unknown authority certification block occurs, follow the tutorial below to solve the problem:

[https://docs.docker.com/engine/security/certificates/](https://docs.docker.com/engine/security/certificates/)

info

It is important to point out that this tutorial is subject to changes by Docker Inc. and is not controlled by SoftExpert.

Increase the number of concurrent PHP processes

If you need to raise the limit of simultaneous PHP processes, due to a more intense use, follow the steps below:

1. Access the file:

# vi SESUITE_HOME/suite.env

2. Add the following line:

WWW_CONF=pm.max_children = 80

In this case, there will be up to 80 simultaneous processes.

info

There should be no spaces between WWW_CONF=<variable>

IMPORTANT! The maximum value must be based on the ratio between the amount of available ram memory on the machine and the average amount of memory consumed in each process.

To obtain this result, run the following command:

docker exec -it se-baseclass ps -ylC php-fpm --sort:rss

Where se-baseclass is the name of the container being run. This information can be found in the following command:

docker-compose ps