Appendix - Common issues

It should be noted that while every care has been made to ensure that both the product and the instructions contained in this document are correct it is always possible that problems may arise. This section describes some common issues along with suggestions on how they can be resolved.

Issue - No terms appear in concept mapping

If no terms appear when you perform a search even though you believe there should be, check the following:

• Are you getting any results when you call the Semaphore “conceptmap” service directly?

To call the service directly add “&QUERY=<text>” (replacing text with what you wish to search on) to the “conceptmap” service URL and retrieve this using your web browser. If no terms are displayed in the XML results then this could indicate a problem with the publishing (baseline) process.

• If you are getting terms being returned from calling the service directly but not getting any results in your system then is your system able to call the Semaphore “conceptmap” service correctly?

It could be that network configuration prohibits your system from talking to the Semaphore installation machine. Check your network configuration to ensure that this is not the case.

• Do you see any errors when publishing the model?

Either publish the model to check to see what is displayed or have a look in the Publisher log files in “<Studio Installation Directory>\kmm\logs\publisher-logs\” (when using the publisher plugin).

• If no errors are received during publishing check to make sure the model is correct

The following must be true:

1. For terms to appear in the Semantic Enhancement Server at all they must be approved in the model (unless the publisher configuration has been modified to pick up all terms by set the “includeCandidateTerms” property value to “true”).
2. For terms to appear in concept mapping they must have the attribute “Use for concept mapping” assigned to them and it must be set (after which a full publish must have been run).

Issue - “FREQUENCY” (“FREQ”) Values Returned From Semantic Enhancement Server are all 0

If you are not using any specific publisher configuration for updating the counts in the Count Updater then this is correct behaviour. However, if you are expecting counts to appear please ensure that the publisher configuration file you are using has the “Count Updater” section included (see Count Updater for further details).

Issue - The Classification Analysis Tool will “hang” when attempting to display classification results

This issue effects the web browser interface only, not the underlying classification being performed by Classification Server (for example, any integrations accessing the Classification Server via it’s API will be unaffected). The “Classification Analysis Tool” user interface is scheduled for redevelopment which will address this issue however in the meantime the work-around is to use the “Legacy” interface which provides similar information though not in such a user-friendly way.

Note that this issue typically occurs on classification of a document in “Classification Analysis Tool” when any of the following are true:

1. It is an overly “complex” document (complex in structure, not necessarily long),
2. The classified document is very large,
3. There are a lot of classifications returned for the classified document,
4. There is an excessive amount of evidence in the document for the term selected, or,
5. The rulebase set is very large/complex.

Issue - “java.lang.OutOfMemoryError: Java heap space” from SES request

If you see the error “java.lang.OutOfMemoryError: Java heap space” returned from a SES API request then this likely indicates that the Java maximum amount of memory to be allocated for SES needs to be increased. By default the settings are 512 Mb for both the “Xms” (initial memory pool) and “Xmx” (maximum memory allocation pool). Increasing the “Xmx” setting will allow SES to use more memory, if required, to process the request. This setting can be altered by updating the “<Publisher-SES Installation Directory>\solr\bin\solr.in.cmd” file to uncomment (remove the initial “REM ”) then adjust the set SOLR_JAVA_MEM=-Xms512m -Xmx512m value appropriately, for example, to set it to use up to 2 Gb of memory you would use set SOLR_JAVA_MEM=-Xms512m -Xmx2g. After updating the value you will need to restart the “Semaphore - Semantic Enhancement Server” Windows service so that it picks up the changes.

Issue - KMM “Backup Models” Returns Exceptionally Large File

Often the reason the download generated by using the “Backup Models” option in KMM is exceptionally large is that it includes the publisher output. The publisher output can be very large due to the number of artefacts it generates.

To exclude the publisher output from the backup, on the server where Semaphore Studio is installed create the file “<SEMAPHORE_WORKBENCH_HOME>\workspace\com.smartlogic.workbench.publisher\backupIgnore” (where “<SEMAPHORE_WORKBENCH_HOME>” is the directory set in the “SEMAPHORE_WORKBENCH_HOME” environment variable). Note that the name of the file is case sensitive so it must be “.backupIgnore” (all lowercase except for the “I”). If the “SEMAPHORE_WORKBENCH_HOME” environment variable is not set, then the location defaults to “C:\ProgramData\Smartlogic\Studio\kmm”, so if this is the case then the file to create is “C:\ProgramData\Smartlogic\Studio\kmm\workspace\com.smartlogic.workbench.publisher\backupIgnore”. The “.backupIgnore” file should contain the single line:

results/**

Issue - Lexical Resources Side Panel Returns “Technical issue, invalid MD5”

When attempting to use the “Lexical Resources” side panel in Studio/Knowledge Model Management (KMM) the following error is shown:

Generally this issue is due to an older version of Studio being used. The “Lexical Resources” side panel can only be used in Semaphore 5.0.3 or greater. If you have an earlier version of Semaphore please upgrade to a newer version of Semaphore in order to use this side panel.

Issue - General troubleshooting of Classification Server issues

After reviewing all of the details in this documentation and Classification Server still fails to start a good way to troubleshoot start up issues (or other issues, see below) is to run Classification Server from the command line as some messages shown during start-up may not appear in any of the logs generated by the application. To do this, first log in to the Semaphore server where Classification Server is installed as an administrator (or as someone with administrator permissions) and run the following command (assuming Classification Server is not currently running), taking care to execute as the SAME user (if possible) as the one executing the service (modify the path if installed in another location):

C:\Program Files\Smartlogic\Classification Server\bin\ClassificationServer.exe

The console will now show all start-up messages.

This method can also be used to troubleshoot issues encountered in running Classification Server for which no log messages are available or the messages do not provide the detail required. To do this, first make sure that Classification Server is not running (e.g. stop the Windows service) start Classification Server (as above) and leave running while reproducing the issue. To stop Classification Server when running in the console, simply press CTRL-C (as normal) then you can start the service again as normal (e.g. start the Windows service again).

Issue - Errors shown in model editor (KMM) when restoring

When restoring models (using the “Restore Models” option) the backend and frontend of Knowledge Model Management (KMM) is not available so you will see the following:

This is a known issue that has been noted for resolution in a future release.

Note that when the model restore process has completed, the UI should return to working as normal.