Tech Note



[pic]

Touchpaper Support

Email: support@

Tel: +44 (0) 1483 744449 Fax: +44 (0) 1483 727428

Address: Dukes Court, Duke Street, Woking, Surrey, GU21 5RT

Technical Note: CONSOL0002

Title: Installing and Troubleshooting Core Knowledge

Technote Version : 1.4

Product : Console and Core knowledge

Version : 7.1.1 +

Environ : Windows

Date : 04/01/2007

What's the difference between ActiveKnowledge and Core Knowledge? 3

Configuration: 3

Config1 - Install checks 3

Config2 - Installing verity on another server 3

Config3 - Configuration for building incidents into the knowledge engine 3

Config4 - Do you want the knowledge search to automatically run? 3

Config 5 – How often do you want the rebuild to run? 3

Basic Troubleshooting Steps: 3

Troubleshooting Step 1 – Checking the collections 3

Troubleshooting Step 2 – Checking what will be in the build 3

Troubleshooting Step 3 – Checking the build has completed 3

Troubleshooting Step 4 – Forcing a MetaData refresh (example - build is not including all objects and attributes specified) 3

Troubleshooting Step 5 – Error Logging 3

Troubleshooting Step 6 - How to delete old failed or pending Knowledge Management queue messages 3

Troubleshooting Step 7 – How do I know that the build is actually working? 3

Troubleshooting Errors: 3

If the knowledge rebuild keeps saying in progress and never completes: 3

If the Verity Server name has changed or if you have restored a database onto another machine for testing: 3

Going into the Knowledge Management Administration - Knowledge Settings - Verity settings no verity server is displayed or you see a "The Knowledge configuration is missing" message 3

In event viewer for the Touchpaper Knowledge Builder: “The request failed with a status HTTP 404 not found” 3

In queue entries An Error occured while parsing Entity Name, line 1 position 14. 3

In event viewer for the Touchpaper Knowledge Builder: Object reference not set to an instance of an object 3

In event viewer for the Touchpaper Knowledge Builder: An error occured whilst attempting to purge the collection." 3

Logging and Tracing 3

What's the difference between ActiveKnowledge and Core Knowledge?

ActiveKnowledge is Touchpaper's new Knowledge Management product and provides a wide and powerful range of business benefits.

Core Knowledge is a term used to describe the basic knowledge functions provided within by default within Touchpaper's ServiceDesk.

Core Knowledge provides the same features as ActiveKnowledge, but does not include the following which can only be obtained by purchasing the full ActiveKnowledge product.

ServicePortal Components: Search, Browse, Ask, Most Popular, Most Recent.

Knowledge Domains : defining, structuring, filtering and restricting knowledge to the correct recipients

Document scanning : indexing existing business documentation

Learned Effectiveness : Learning the business value of your knowledge and using that to present known-good solutions.

NOTE: Core Knowledge is installed from the ServiceDesk CD whereas Active Knowledge is on another separate CD.

Configuration:

Config1 - Install checks

Before you start to configure core knowledge you need to verify the installation. Here are the components to check:

Is the java sun development kit (sdk) installed?

[pic]

Are the two verity k2 services running? NOTE: Preferably verity will be installed on a separate server to the application server. See section – Installing Verity on Another Server.

[pic]

Have you installed the verity k2 patch (run K2TK600_p1_nti40Install.exe)?

[pic]

NOTE: When installing verity you will require a verity licence number which you can obtain from support. This will not be asked for when just installing the patch.

Are the core Touchpaper Knowledge Builder and the Knowledge Management Engine installed?

[pic]

If so, are the 2 Touchpaper knowledge services are both running? (See also the section Config 5 regarding how to make the decision about whether you want Knowledge Management Engine running or not)

[pic]

Config2 - Installing verity on another server

The verity services should be installed on the verity server. The Touchpaper knowledge builder and the knowledge base services should be installed on either the application server OR the verity server. We recommend the verity server for simplicity in managing the services.

Ensure that the correct verity server name is displayed in the Knowledge Management Administration component – Activeknowledge Settings – Verity Settings.

[pic]

This is populated when the knowledge services start and 'scan' the network for the location of the K2 Master Administration server. This server name is then stored in the tps_application_settings table in the database.

NOTE: See the troubleshooting section for how to change this server name.

Config3 - Configuration for building incidents into the knowledge engine

You need to select which objects and which attributes will be included in the build. This example is for including Incidents.

In Console do the following steps to ensure that the incidents are built into core knowledge:

Object Designer - Ensure that incident management - incident is set to knowledgeable TRUE.

[pic]

Object Designer - Ensure that process management - process is set to knowledgeable TRUE.

Do the following steps to ensure that the right attributes are searched on when searching core knowledge:

Object Designer - Open process management - process go into the attributes and set the relevant attributes to "natural language" or "exact" (suggested attributes would be TITLE and DESCRIPTION).

A natural language search is a search using regular spoken language, such as English. Using

this type of search you can type a sentence that describes the information you are looking for.

An exact match search is a search for text that matches your search exactly.

Note: Natural Language is the setting most commonly used.

[pic]

In ServiceDesk open up the Knowledge Management Administration component - Attributes - Knowledgeable Objects - Incident Management - check Incident is ticked.

[pic]

Also look at Search Layout to see what will be displayed on your search results window. Right-click on any attributes you want to appear in the search results window and select Add to Search Layout. NOTE: Suggested attributes would be TITLE and DESCRIPTION.

Still in Knowledge administration - Attributes - Knowledgeable Objects go to Process Management - check Process is ticked plus the sub-sections of the Incident process. Again look at Search Layout and right click on any attributes you want to appear in the search results window and select Add to Search Layout. NOTE: Suggested attributes would be TITLE and DESCRIPTION.

NOTE: You should just need to do this for Process, as Incident, Problem and Change all inherit from Process.

NOTE: You can perform this change in either Object Designer or Knowledge Administration.

Config4 - Do you want the knowledge search to automatically run?

You can manually run a knowledge search either via the Knowledge Management Search component or by highlighting text then selecting the Search In Knowledgebase icon. However if you want an automatic search, then you need to configure which fields the auto search will work from via Window Designer. Once you have located your screen and high-lighted the required field, expand the Properties tree, then alongside the Search Type property, select the relevant option. None -Indicates that you do not want to include the control in a search. This is the default option. Free Text – Indicates that you want to search on all of the text entered into that control.

Then under Invoke Search On select the required settings.

[pic]

For example the above configuration will mean that when you lose focus on the incident description field the knowledge search will automatically invoke:

[pic]

IMPORTANT! Think carefully about these settings and alter depending on the type of field you are configuring. For example, if you are configuring a large text field then you would be more likely to use “Lose Focus”. If you select End of word, White space character, or Punctuation character on a large text field then knowledge will be constantly starting new searches as you fill the field with text. This may make the user think that the system has hung or frozen whilst it tries to finish all of the searches. However, if it is a field which can only contain one word in it, then using End of word might be an appropriate setting.

Config 5 – How often do you want the rebuild to run?

Once the rebuild has completed you shouldn’t need to rebuild on a frequent basis. Each time that you rebuild knowledge it purges the knowledge collection and then rebuilds from scratch. If you have a large number of knowledgeable objects then this could take some time to complete.

After you have rebuilt the knowledge once, it will be adding in objects to the knowledge collection as they are added or updated. You only need to rebuild the whole knowledge collection again should there be an issue. IMPORTANT! If you do not want the knowledge to automatically rebuild then ensure that the Knowledge Management Engine application or service is not running.

Basic Troubleshooting Steps:

Troubleshooting Step 1 – Checking the collections

The first thing that the Knowledge Builder service does when it runs for the first time is to connect to the database and build the collection structure. One way to check that these have been created is to run the Verity dashboard from the Verity program group and expand the Collections folder. Are there 3 tps_* folders displayed? This indicates whether the build is even starting ok to create the initial collections.

NOTE: The reason there are 3 collections built is for robustness. For example if one is being built you can still search the knowledge base using the others (as long as you have had previous successful builds).

[pic]

This creates the collections in the following file path:

\Program Files\verity\k2_6\data\colls\tps_coll_master\style

\Program Files\verity\k2_6\data\colls\tps_coll_slave_one\style

\Program Files\verity\k2_6\data\colls\tps_coll_slave_two\style).

If they are not created then it is likely that the Knowledge Builder is unable to connect to the database (via Touchpaper Services) or cannot logon. See Troubleshooting Errors.

Troubleshooting Step 2 – Checking what will be in the build

You can see what will be included in the Knowledge Build listed in the style.xml file for verity (this is located in three places, but you just need to look at one of them as the Verity Services ensure they are synchronised:

C:\Program Files\verity\k2_6\data\colls\tps_coll_master\style

C:\Program Files\verity\k2_6\data\colls\tps_coll_slave_one\style

C:\Program Files\verity\k2_6\data\colls\tps_coll_slave_two\style).

Troubleshooting Step 3 – Checking the build has completed

In Knowledge Management Administration - Knowledge Settings - Queue Entries you can see what the knowledge base service has tried to rebuild or process. You can double-click on completed entries to see what was in the build displayed within a report. For example you should be able to expand the incidents section to see the incidents included in the build.

[pic]

NOTE: If the rebuild has included a very large number of knowledgeable objects then the system will not be able to display the results on the screen. This is because there is a generic size restriction of 4MB on the .xml report it is displaying being sent to the database. You will typically get a message in the event log about “cannot save .xml document” or similar if this is the case. The report is still produced but not uploaded to the database and so not viewable via knowledge management. The report is located in c:\windows\temp and you can open it in notepad or in an .xml viewer.

Troubleshooting Step 4 – Forcing a MetaData refresh (example - build is not including all objects and attributes specified)

On occasion the changes made in Object designer (stored in the database as metadata) are not being picked up by the Knowledge Builder Service. You can tell this by seeing if incident attributes are listed in the style.xml file for verity (see troubleshooting step 3). To force the Knowledge Builder Service to pickup the object designer changes that you made you can force a metadata refresh by doing the following in Object Designer:

Object Designer - Ensure that incident management - incident note is set to knowledgeable TRUE.

Switch to FALSE and save changes.

Switch to TRUE and save changes.

NOTE: Can do this on any Class, does not have to specifically be an Incident Note

This means that when looking in Knowledge Management Administration - Knowledge Settings - Queue Entries there should be a queue processing with a message type of "Meta Data Change". After this is run check that the style.xml file now contains entries for the incident attributes.

NOTE: The Meta Data Change does not do a rebuild so you may need to also run a rebuild afterwards.

NOTE: When completed successfully Meta Data Change queue entries are deleted unlike rebuild queue entries which remain.

Troubleshooting Step 5 – Error Logging

You can increase the amount of detail written to the event log for any errors by stopping the service, editing the file \Touchpaper Knowledge Builder\Touchpaper.Service.KnowledgeBuilderService.exe.cfg to change the line:

To

And then restart the Knowledge service and have a look to see what is in the event log.

IMPORTANT: Remember to change back when you have finished troubleshooting as the event log will quickly fill up!

Troubleshooting Step 6 - How to delete old failed or pending Knowledge Management queue messages

This should be done to clear out any old queue messages and start afresh. The service should be stopped prior to running the command and then restarted afterwards.

delete FROM km_knowledge_message

Troubleshooting Step 7 – How do I know that the build is actually working?

Check that the “k2 index server” process is running in task manager as this indicates that the build is running.

Troubleshooting Errors:

If the knowledge rebuild keeps saying in progress and never completes:

This is normally when the Touchpaper Knowledge Builder service is not running or is not configured correctly. Look in the event viewer -application log to see if you are getting database connection errors. If so check the C:\Program Files\Touchpaper Software\Touchpaper Knowledge Management Engine\Touchpaper.Service.KnowledgeManagement.WindowsService.exe.cfg and \Touchpaper Knowledge Builder\Touchpaper.Service.KnowledgeBuilderService.exe.cfg has the correct URL to touchpaper services plus the correct sa login and password.

If the Verity Server name has changed or if you have restored a database onto another machine for testing:

1. Stop Knowledge Builder Service.

2. Delete from tps_application_setting WHERE (tps_name = 'VeritySettings')

3. Restart Knowledge Builder Service.

Going into the Knowledge Management Administration - Knowledge Settings - Verity settings no verity server is displayed or you see a "The Knowledge configuration is missing" message

Check that the Touchpaper Knowledge Knowledge Base Service is running. If it is check the application event log for errors (which might indicate connection details so check the C:\Program Files\Touchpaper Software\Touchpaper Knowledge Management Engine\Touchpaper.Service.KnowledgeManagement.WindowsService.exe.cfg and \Touchpaper Knowledge Builder\Touchpaper.Service.KnowledgeBuilderService.exe.cfg)

If the above doesn’t fix the issue, "The knowledge configuration is missing" can also be resolved by purging the collections (if a collection has previously been built on this server) or by restarting the verity services.

In event viewer for the Touchpaper Knowledge Builder: “The request failed with a status HTTP 404 not found”

Check which Touchpaper Services URL is specified in \Touchpaper Knowledge Builder\Touchpaper.Service.KnowledgeBuilderService.exe.cfg and compare this with the console.exe.config file. These should be identical if you only have one TPS installed.

In queue entries “An Error occurred while parsing Entity Name, line 1 position 14.”

 

When you double click the error “Unhandled exception error Root Element is Missing”

One of the knowledge-able objects may be causing this, there may be strange characters which have been imported into it which the builder cannot handle. Exit Console, do iisreset, and verify the knowledgeable objects are as expected via object designer (for example Assets may be switched on as knowledgeable). Also try removing the xml files via knowledge administration or from the \temp folder on the server.

In event viewer for the Touchpaper Knowledge Builder: Object reference not set to an instance of an object

This message could mean a couple of things:

• It could be complaining about one of the business objects which is set to be knowledgeable. Change all objects to being not knowledgeable and rebuild knowledge (this should happen automatically as you have made a metadata change). Then switch only the required objects to be knowledgeable OR switch on each object one at a time to find out which object is causing the rebuild to fail.

• Alternatively it could mean that it cannot login using the login credentials supplied under Touchpaper.Service.KnowledgeBuilderService.exe.cfg and Touchpaper.Service.KnowledgeManagement.WindowsService.exe.cfg.

One way to ascertain which is to switch the error logging to Information (see Error Logging for details) and if the message below is written to the event log then this means that this is an issue logging in:

Description:

NullReferenceException Object reference not set to an instance of an object.

Stack Trace:

   at Touchpaper.Framework.SystemServices.binedExtension.TryExplicitLogon(ITpsCredentials tpsCredentials, ValidatedCredentials& validatedCredentials)

  

For example, in one instance this was seen because the console.config held the TPS Host" and Url" value with the machine name whereas the Touchpaper.Service.KnowledgeBuilderService.exe.cfg held it as localhost. If in doubt take then two lines from console.config and paste into Touchpaper.Service.KnowledgeBuilderService.exe.cfg to ensure that they are identical.

In event viewer for the Touchpaper Knowledge Builder: An error occurred whilst attempting to purge the collection." 

You can manually purge the collections via the verity K2 dashboard. NOTE: Do not delete the collections PURGE them! If you delete the collections you will need to uninstall then reinstall Verity.

“There was an error in XML Document…" and it gives a position e.g (39,-1099).

This can be caused by characters imported into the knowledgeable objects in the database which the .xml parser cannot handle. Look at the .xml file(s) in the \temp folder on the server to see at what stage the issue happened plus switch on diagnostic error logging and tracing to see if you can identify what character or object is causing the issue. We may be able to provide scripts to strip these out – contact support for advice.

In queue entries “Error parsing attribute”

Stop the builder service. Check the \temp folder on the server and rename / move any .xml files which have been generated by the builder. Restart the builder service.

Logging and Tracing

If you want to diagnose intermittent behaviour or trace what the search is doing there are some diagnostic settings that you can switch on. These should be switched off again as soon as the problem is captured so that the performance of the system is not adversely affected for too long.

Logging the searches sent to Verity from console

You can edit the Console.exe.config file located in C:\Program Files\Touchpaper Software\Touchpaper Console to add the key below:

This should put entries into the event logs to show you the statements being sent to verity.

Verity Server Logging

This is extracted from the Verity K2 Dashboard Administrator Guide - Adding and Managing K2 Ticket Servers. You need to change these settings by running the K2 dashboard available from your Verity program group.

Editing Logging Properties

1. Select the Logging tab.

2. Enter the desired size for the status log in the Status Log Nominal Size field.

You can limit the size of the generated status log for a K2 Ticket Server. By default, K2 sets the size of status logs to 300 KB. You can increase this value to diagnose issues, especially in conjunction with the verbose logging level.

3. In the Log Level field, select one of the logging levels from the drop-down list.

K2 offers you the following values for status logging levels, in increasing detail:

Fatal

Error

Warning

Status (this is the default)

Verbose

These levels allow you to increase the log detail when you need more information for troubleshooting. Note that increasing log detail can affect system performance.

Log levels are cumulative. For example, if you select the verbose level, error messages for all five levels are displayed. If you select the status level, error messages for the first four levels are displayed, and so on.

4. Click Modify. K2 prompts you to perform a full restart on the K2 Ticket Server.

5. Perform the restart by clicking the Start/Stop Service link and then Full Restart. K2 applies the changes to the system. For more information on restarting a K2 Server, see Starting and Stopping Services.

When you next refresh the status log for the K2 Ticket Server, K2 displays data according to the revised log level. For more information, see Viewing a Service Log.

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download