NS DISCOVER 4.0 ADMINISTRATOR S GUIDE July, 2015 Version 4.0
TABLE OF CONTENTS 1 General Information... 4 1.1 Objective... 4 1.2 New 4.0 Features Improvements... 4 1.3 Migrating from 3.x to 4.x... 5 2 Installation... 6 2.1 Platform Support... 6 2.2 Server Sizing... 6 2.3 Preparation... 7 2.3.1 Identify Host Servers... 7 2.3.2 Register and Download Software... 8 2.4 Upgrade Installation Process... 9 2.4.1 Shutdown NSD Services... 9 2.4.2 Backup the Current Install Folders... 9 2.4.3 Uninstall NorthRidge Discover... 10 2.4.4 Install NorthRidge Discover... 10 2.4.5 Update Configuration Files... 11 2.4.6 IE Browser Cache... 13 2.5 Installation Process... 14 2.5.1 NSD-Search Install... 14 2.5.2 NSD-AppService Install... 17 2.5.3 NSD-AI Install... 23 2.5.4 NSD-FS Install... 29 2.5.5 NSD-WS Install... 33 2.6 License Management... 37 3 Post Installation Configuration... 38 3.1 Aras Innovator Configuration... 38 3.1.1 Adding Discover Innovator Item Type... 38 3.1.2 Icon Images for Results... 40 3.2 Discover Innovator Connector Configuration... 41 3.2.1 Adding Innovator Item Types... 41 3.2.2 Adding Innovator Item Properties... 42 3.3 Starting Services... 45 3.3.1 Search Service... 45 3.3.2 Application Service... 45 Page 2
3.3.3 Connector Services... 46 3.4 Discover Innovator Email Configuration... 47 3.5 Reset Search Index & Full Connector Crawl... 48 3.5.1 Reset the Search Index... 48 3.5.2 Execute Full Connector Crawl... 48 4 Troubleshooting... 49 4.1 Client Errors... 49 4.1.1 Client Generates License Error... 49 4.1.2 Login Dialog Appears Needing Username and Password... 49 4.1.3 Print Button Inactive... 49 4.2 Connector Issues... 49 4.2.1 Incremental Feeds not Processing... 49 5 Supported File Formats... 54 Page 3
1 GENERAL INFORMATION 1.1 OBJECTIVE The objective of this document is to provide the NS Discover administrator with the information required to install and maintain all Discover product/solution suite components. This guide includes instructions for the installation and configuration of: Discover Innovator and Enterprise Applications NS Discover Server Index o Apache Solr 4.10.3 NS Discover Application Service Discover Innovator Connector Discover File Share Connector Discover Web Site Connector 1.2 NEW 4.0 FEATURES IMPROVEMENTS The following table captures details regarding recent feature enhancements. Feature Notes Accuracy Improvements Result and filter document counts are more accurately calculated at search time. Relationship Searches Queries can be performed across documents and their relationship properties. This feature is enabled by default for Documents and their related Files. Relationship Expansion A search criteria can specify that the results be expanded during the query process. Expansion options include: Parent, Child or Both. Performance and Scalability The NS Discover architecture can now handle clustered search indexes configured to support hundreds of millions of documents. Aras Innovator Discover Innovator has been validated for the 10.x and 11.x releases of Aras Innovator. Search Form Form fields identified as required will be validated. Multi-select fields are now supported. Web Browsers Internet Explorer 10 and 11. File Share Connector The File Share Connector can add enterprise documents located within Windows file shares into the search index. Available as part of an enterprise solution suite. Web Site Connector The Web Site Connector can add content from your intranet and internet web sites into the search index. Available as part of an enterprise solution suite. Search with Auto-suggestions Available as an add-on consulting solution. Structured Search Supports deep hierarchical searching through multiple relationship types. Available as an add-on custom solution. Page 4
Discover Innovator Note: In order to deliver many of these new features, the NS Discover security model was redesigned in the 4.0 release. All item permissions are now stored within the search index. By default, Discover Innovator supports the default Aras Innovator permission model. If your site uses a custom or private permission model, then additional consulting services may be required to recognize your unique item permissions. Please contact the NorthRidge Software Support Team if you have any questions about this requirement. 1.3 MIGRATING FROM 3.X TO 4.X This section identifies areas of change between the NS Discover 3.x and 4.x releases. A more detailed explanation of these changes is covered in section 2.4 of this document. Customers migrating from a 3.x release to 4.x will need to have their license.properties file upgraded. Section 2.4.5 provides further details. The latest release of NS Discover is capable of processing much larger document counts. As a result, all software components are now distributed as 64 bit executables. Newer versions of Apache Solr and Tika are included in this release and will require the re-crawling of all content sources. The NSD-Innovator component is no longer included. Its features are now bundled in the Windows service component NSD-AppService. The NSD-RDBMS component is no longer required. The search index is used for application storage. Several configuration files have been redesigned and improved. Backup all existing configuration files (snippet, data source, properties) and follow the steps outlined in section 2.4. The Discover Innovator application URL has changed to http://hostname:8080/ns/discoverinnovator.html. The existing Aras Innovator TOC items must be updated. Section 2.4.5.4 provides further details. Consulting services are available from NorthRidge Software to help those customers who wish to accelerate their NS Discover upgrade process. Page 5
2 INSTALLATION The Administrator is advised to review the entirety of this document in order to properly understand and be prepared for a successful installation. 2.1 PLATFORM SUPPORT The following table identifies the platforms upon which you can deploy and run the NorthRidge Discover suite of products. Component OS Version Index Server Windows Server 2008, 2008 R2, 2012 R2 Windows 7, 8 Discover Innovator Windows Server 2008, 2008 R2, 2012 R2 Connector Windows 7, 8 Discover Innovator Client Internet Explorer 9, 10, 11 2.2 SERVER SIZING The Index Server is typically sized based on the number of documents it will process. However, there can be many other variables involved (e.g. queries per second, average document sizes, etc.), so the table below should be considered a starting point for hardware resource planning. Documents Disk Space (GB) RAM (GB) CPU Cores 10,000.5 2 2 100,000 5 4 2 1,000,000 50 6 4 Although the number of users concurrently searching against the index will affect the performance, the estimates provided above should be sufficient to support hundreds of users. In addition, you should note that scaling vertically and horizontally is also possible with this architecture. Given this flexibility, we recommend keeping the initial configuration simple and deferring the use of a more sophisticated approach (e.g. cluster nodes, load balancers, etc.) until the production usage patterns justify that level of investment. Page 6
2.3 PREPARATION The following steps must be taken before beginning the installation process. 2.3.1 IDENTIFY HOST SERVERS NS Discover is comprised of two primary server components and one or more content connectors. During a product evaluation period, all of the components can be installed on the same machine to simplify the deployment process. Production configurations typically distribute the components among different server machines. 2.3.1.1 NS DISCOVER SEARCH SERVER The NS Discover Search Service is based on the Apache Lucene/Solr technology stack. This component of the architecture is responsible for providing a repository for all the content in a centralized index, optimized for the search and retrieval of results. This platform is scalable to millions of documents and can be configured to meet specific customer requirements. 2.3.1.2 NS DISCOVER APPLICATION SERVICE The NS Discover Application Service hosts application logic and the web client user interface. It is responsible for authenticating the active users, processing their query requests and ensuring their access to documents is based on the permission model of the content source. The application service must be installed on the same server where Aras Innovator has been installed. 2.3.1.3 DISCOVER INNOVATOR CONNECTOR The Discover Innovator Connector is responsible for extracting content from a populated Aras Innovator instance and feeding the data into the NS Discover Search Index. The connector is also responsible for retrieving and opening files that have been requested by the user from the Discover Innovator client. The Discover Innovator Connector must be installed on the same machine where the Innovator Vault Server resides. An Innovator account is required to install the Discover Innovator Connector. You must ensure that the Innovator account used for the installation has read access to all files stored within the Aras Innovator vault folders you wish to index. 2.3.1.4 FILE SHARE CONNECTOR The Discover File Share Connector is responsible for extracting content from a Windows file share. The connector supports full and incremental crawls of the content and provides a document viewing capability for any Discover search client. 2.3.1.5 WEB SITE CONNECTOR The Discover Web Site Connector is responsible for extracting content from an intranet/internet web site. The connector honors robots.txt configurations and can be configured to limit crawl depths within web sites. Page 7
2.3.2 REGISTER AND DOWNLOAD SOFTWARE A license file for NS Discover can be obtained by completing a license request form on the NorthRidge Software web site. You can locate the license request form within the Contact Us menu on the main web page. Simply select the License menu entry and you will be directed to a request form like the one shown below. After you populate the form and submit it, you will receive a reply email message that contains: NS Discover license file Links to download the software Links to the installation instructions Page 8
2.4 UPGRADE INSTALLATION PROCESS Follow these steps before running the NorthRidge Discover installation program if you are upgrading from a previous version other than Discover Innovator 4.0. If upgrading from release 3.5, the path to the currently installed files will be as described in section 2.4.2. This process will remove your existing index and repopulate the index with a full feed. 2.4.1 SHUTDOWN NSD SERVICES Open the Windows Services dialog from the server on which each of these services are currently running. They can be located on a single server or may be distributed across multiple servers. Stop each of the services before proceeding. NSD-CON-AI NSD-Innovator NSD-Index NSD-RDBMS The number of services running in your environment may vary depending on the products you currently have installed. 2.4.2 BACKUP THE CURRENT INSTALL FOLDERS Navigate to the current NorthRidge Discover installation folder (NS_HOME). If upgrading from a release previous to 4.0, copy the following folders to a separate backup folder. [NS_Home] \NSD-CON-AI [NS_Home] \NSD-Index [NS_Home] \NSD-Innovator Page 9
[NS_Home] \NSD-Enterprise [NS_Home] \NSD-RDBMS 2.4.3 UNINSTALL NORTHRIDGE DISCOVER Open the Windows Uninstall or change a program dialog. Uninstall each of the NS Discover programs. If upgrading from release 4.0, navigate to [NS Home] and delete the NSD-CON-AI, NSD- Index, NSD-Innovator and NSD-RDBMS folders. 2.4.4 INSTALL NORTHRIDGE DISCOVER Follow the instructions in section 2.5 to install the latest version of NS Discover. NOTE: Do not start the NS Discover services as described in section 3 until you have completed the post-installation configuration process. Page 10
2.4.5 UPDATE CONFIGURATION FILES The installation of the latest version of NorthRidge Discover will include the default configuration files based on the values you provided to the questions of the install wizard. There are some configuration parameters that you may have changed in the previous version to effect the behavior of NS Discover to meet your specific operational requirements. Those changes will need to be re-applied to the new 4.0 installation area. In some instances the configuration property names and XML field formats may have changed, so if you are unsure about where an update should be made, please contact the NorthRidge Software Support Team for assistance. Note: Customers migrating from a 3.x release to 4.x will need their license.properties file upgraded. The location of the file is identified below. Please email it to the NorthRidge Software Support Team to have it upgraded and sent back to you. \NSD-Innovator\Service\tomcat32\webapps\innovator\WEB-INF\classes\license.properties The remainder of this section references the configuration files you backed up in section 2.4.2. 2.4.5.1 MIGRATING NSD-CON-AI CONFIGURATION FILES The connector for Aras Innovator was redesigned to support a new more scalable architecture. Most of the configuration options are still available, but the file and property names have changed. \NSD-CON-AI\Service\cfg\application.properties was moved to \NSD-AI\Service\cfg\application.properties Old Property Name connector.run_full_time connector.run_sleep_time connector.run_incremental_time connector.content_character_limit connector.vault_folder connector.server_time_hour_delta connector.item_types connector.mail.* New Property Name connector.ai.run_full_interval connector.ai.run_sleep_between connector.ai.run_incremental_interval connector.ai.extract.content_limit connector.ai.extract.vault_folder connector.ai.extract.server_time_hour_delta Specified in crawl_start.txt file connector.ai.mail.* \NSD-CON-AI\Service\cfg\ai_item_fields.xml was moved to \NSD-AI\Service\ds\ds_ai_schema.xml All site specific properties stored in the ai_item_fields.xml must be copied to the ds_ai_schema.xml. Section 3.2.2.2 provides some helpful information on the field format of this file. Old path: \NSD-CON-AI\Service\ds New path: \NSD-AI\Service\ftl Page 11
This folder contains the configuration files that include the AML queries that identify the Innovator properties that will be extracted for indexing. Review the differences between the backup and new versions of the query files for each item type you are indexing. Please note that there is no longer a need to maintain a separate incremental version of the query template file. Section 3.2.1.1 provides some helpful information about these template files. 2.4.5.2 MIGRATING NSD-INDEX CONFIGURATION FILES Old path: \NSD-Index\Service\solr-4.9.0\solr\discover\conf New path: \NSD-Search\Service\solr-4.10.3\solr\nsdoc\conf This folder contains two configuration files that control the behavior of the Apache Solr index. solrconfig.xml schema.xml All site specific fields in each of these files must be copied to the same corresponding file in the new folder. Be careful to only copy fields that were previously common to all Discover Innovator installations those fields have been renamed to better support enterprise search installations. Section 3.2.2.3 provides some helpful information about these files. 2.4.5.3 MIGRATING NSD-INNOVATOR CONFIGURATION FILES \NSD-Innovator\Service\tomcat32\webapps\innovator\ds\dsd_SolrOSS.xml was moved to \NSD-AppService\Service\ds\ds_solr_nsdoc.xml All site specific fields stored in the dsd_solross.xml must be copied to the ds_solr_nsdoc.xml. Section 3.2.2.4 provides some helpful information on the field format of this file. \NSD-Innovator\Service\tomcat32\webapps\innovator\WEB-INF\classes\di1_snippet.ftl was moved to \NSD-AppService\Service\tomcat7\webapps\ns\WEB-INF\classes\di_snippet_parent.ftl Review the di1_snippet.ftl template file and copy the site specific changes to the new di_snippet_parent.ftl template file. Page 12
2.4.5.4 MIGRATING ARAS INNOVATOR TOC URL The Discover Innovator URL changed from http://hostname:8080/innovator/d1.html to http://hostname:8080/ns/discoverinnovator.html. The existing TOCs must be updated. Refer to section 3.1.1 for details. 2.4.6 IE BROWSER CACHE We strongly recommend that every NS Discover user clear their IE browser cache before running the new release of an application. This is only required for customers upgrading from a previous version of NS Discover. Page 13
2.5 INSTALLATION PROCESS The following sections describe in detail the step-by-step instructions for installing NS Discover and related search products. The following table identifies which install programs must be run in order to deploy the desired NS Discover applications. Product/Solution Installer Sequence Comments Discover Innovator NSD-Search NSD-AppService NSD-AI NSD-AppService should be installed on the Aras Innovator server machine. The NSD-AI connector should be installed on a machine where it will have access to the Aras Innovator vault files. Discover Enterprise NSD-Search NSD-AppService NSD-FS NSD-WS These components can co-exist with an existing Discover Innovator installation. In that scenario, you will only need to install the file share and web site connectors. 2.5.1 NSD-SEARCH INSTALL Follow these steps to install the NS Discover Search Index software. The installer can be downloaded from The NorthRidge Software web site as described in section 2.3.2. 1. Start the NSD-Search_windows-x64_4_0_15.exe installation program. The welcome dialog is presented. 2. Select the Next button to proceed. 3. The end user license agreement dialog is displayed. Page 14
4. Choose to accept the license agreement after reviewing the text. The Next button will then become enabled. 5. Select the Next button to proceed. 6. The destination selection dialog is presented. 7. Use the Browse button to navigate to the folder where you wish to install the software or accept the default directory as displayed. 8. Select the Next button to proceed. Page 15
9. Select the Next button to proceed to the Start Menu dialog. 10. Provide a new folder name or accept the default as shown above. 11. Selecting the Next button will begin the installation process and present the following status dialog. 12. Upon completion of the installation, the following dialog is displayed. Page 16
13. Select the Finish button to complete the installation. 2.5.2 NSD-APPSERVICE INSTALL Follow these steps to install the NS Discover Application Service. The installer can be downloaded from The NorthRidge Software web site as described in section 2.3.2. This install deploys the NS Discover Application Service software that allows the administrator to configure and deploy multiple NS Discover client applications. This install must be run on the Aras Innovator server machine. 1. Start the NSD-AppService_windows-x64_4_0_15.exe installation program. The welcome dialog is presented. 2. Select the Next button to proceed. Page 17
3. The end user license agreement dialog is displayed. 4. Choose to accept the license agreement after reviewing the text. The Next button will then become enabled. 5. Select the Next button to proceed. 6. The destination selection dialog is presented. Page 18
7. Use the Browse button to navigate to the folder where you wish to install the software or accept the default directory as displayed. 8. Select the Next button to proceed to the NS Discover Application Service Property Configuration Form. Complete the form as described below. Page 19
a. NSD Application Service Host Name enter the host name that this server will be known by on the network. You will use this same host name during the installation process for the connectors later in the administration guide. Note: The Application Service host name or FQDN is interpreted in a case sensitive manner. Therefore, you must ensure the name provided is consistent. We recommend using lowercase at all times. b. NSD Search Service Host Name - enter the host name of the server on which you installed the NSD Search Service in the previous section. c. Aras Innovator Server URI enter in the complete URL to the Aras Innovator service. The default for a configuration where everything resides on one machine is http://localhost/innovatorserver/server/innovatorserver.aspx. Note: Make sure that you replace the default "localhost" with the actual host name of the Aras Innovator server. To validate that you have the correct URL, copy it into the address bar of your web browser. You should see a reply message similar to the one below. d. Aras Innovator Client URI enter the complete URL to the Aras Innovator client. The default for a configuration where everything resides on one machine is http://localhost/innovatorserver/client/default.aspx. Note: Make sure that you replace the default "localhost" with the actual host name of the Aras Innovator server. This is the same URL that invokes the Aras Innovator Web Client. To validate that you have the correct URL, copy it into the address bar of your web browser. It should launch the Innovator Web Client. e. Aras Innovator Database Name enter the name of your company's Innovator Database as identified in the id field in the example below. <DB-Connection id="demo10" database="demo10" server="(local)" uid="innovator" pwd="innovator"/> f. Aras Innovator Account Name enter the name of the user that will be used to programmatically log in to Innovator to extract the content to the index. Page 20
The account name provided must have read access to all of the Innovator items you wish to include in the search index. g. Aras Innovator Account Password enter the password for the user you identified as the Aras Innovator Account Name. 9. Select the Next button to proceed to the Start Menu dialog. 10. Provide a new folder name or accept the default as shown above. 11. Selecting the Next button will begin the installation process and present the following status dialog. Page 21
12. Upon completion of the installation, the following dialog is displayed. 13. Select the Finish button to complete the installation. Page 22
2.5.3 NSD-AI INSTALL Follow these steps to install the Discover Innovator Connector software. The installer can be downloaded from the NorthRidge Software web site as described in section 2.3.2. This install must be run on the server where the Aras Innovator vault files are located. 1. Start the NSD-AI_windows-x64_4_0_15.exe installation program. 2. The welcome dialog is presented. 3. Select the Next button to proceed. 4. The end user license agreement dialog is displayed. Page 23
5. Choose to accept the license agreement after reviewing the text. The Next button will then become enabled. 6. Select the Next button to get to the destination selection dialog. 7. Use the Browse button to navigate to the folder where you wish to install the software or accept the default directory as displayed. 8. Select the Next button to get to the Properties Configuration Form. Page 24
Complete the form as described below a. NSD Application Service Host Name enter the same host name you provided earlier during the NSD AppService installation process (step 8a). b. NSD Search Service Host Name - enter the host name of the server on which you installed the NSD Search Service in a previous section. c. Aras Innovator Server URI enter in the complete URL to the Aras Innovator service. The default for a configuration where everything resides on one machine is http://localhost/innovatorserver/server/innovatorserver.aspx. Note: Make sure that you replace the default "localhost" with the actual host name of the Aras Innovator server. To validate that you have the correct URL, copy it into the address bar of your web browser. You should see a reply message similar to the one below. Page 25
d. Aras Innovator Client URI enter the complete URL to the Aras Innovator client. The default for a configuration where everything resides on one machine is http://localhost/innovatorserver/client/default.aspx. Note: Make sure that you replace the default "localhost" with the actual host name of the Aras Innovator server. This is the same URL that invokes the Aras Innovator Web Client. To validate that you have the correct URL, copy it into the address bar of your web browser. It should launch the Innovator Web Client. e. Aras Innovator Database Name enter the name of your company's Innovator Database as identified in the id field in the example below. <DB-Connection id="demo10" database="demo10" server="(local)" uid="innovator" pwd="innovator"/> h. Aras Innovator Database Vault Path enter the full path to the Innovator vault. The Discover Innovator Connector must be installed on the same server as the Innovator Vault. Note: The folder name selected must include the Innovator database instance name. For example, if the database name is DEMO10, then you would select the following folder. i. Aras Innovator Account Name enter the name of the user that will be used to programmatically log in to Innovator to extract the content to the index. The account name provided must have read access to all of the Innovator items you wish to include in the search index. Page 26
j. Aras Innovator Account Password enter the password for the user you identified as the Aras Innovator Account Name. 9. Select the Next button to get to the Start Menu dialog. 10. Provide a new folder name or accept the default as shown above. 11. Selecting the Next button will begin the installation process and present the following status dialog. Page 27
12. The following dialog is displayed when the software has been completely installed. 13. Select the Finish button to complete the installation. Page 28
2.5.4 NSD-FS INSTALL Follow these steps to install the Discover File Share Connector software. This connector is available as part of the Discover Enterprise solution. The installer can be downloaded from The NorthRidge Software web site as described in section 2.3.2. 1. Start the NSD-FS_windows-x64_4_0_15.exe installation program. 2. The welcome dialog is presented. 3. Select the Next button to proceed. 4. The end user license agreement dialog is displayed. Page 29
5. Choose to accept the license agreement after reviewing the text. The Next button will then become enabled. 6. Select the Next button to get to the destination selection dialog. 7. Use the Browse button to navigate to the folder where you wish to install the software or accept the default directory as displayed. 8. Select the Next button to get to the Properties Configuration Form. Page 30
Complete the form as described below a. NSD Application Service Host Name enter the same host name you provided earlier during the NSD AppService installation process (step 8a). b. NSD Search Service Host Name - enter the host name of the server on which you installed the NSD Search Service in a previous section. 9. Select the Next button to get to the Start Menu dialog. Page 31
10. Provide a new folder name or accept the default as shown above. 11. Selecting the Next button will begin the installation process and present the following status dialog. 12. The following dialog is displayed when the software has been completely installed. 13. Select the Finish button to complete the installation. Page 32
2.5.5 NSD-WS INSTALL Follow these steps to install the Discover Web Site Connector software. This connector is available as part of the Discover Enterprise solution. The installer can be downloaded from the NorthRidge Software web site as described in section 2.3.2. 1. Start the NSD-WS_windows-x64_4_0_15.exe installation program. 2. The welcome dialog is presented. 3. Select the Next button to proceed. 4. The end user license agreement dialog is displayed. Page 33
5. Choose to accept the license agreement after reviewing the text. The Next button will then become enabled. 6. Select the Next button to get to the destination selection dialog. 7. Use the Browse button to navigate to the folder where you wish to install the software or accept the default directory as displayed. 8. Select the Next button to get to the Properties Configuration Form. Page 34
Complete the form as described below c. NSD Application Service Host Name enter the same host name you provided earlier during the NSD AppService installation process (step 8a). d. NSD Search Service Host Name - enter the host name of the server on which you installed the NSD Search Service in a previous section. 9. Select the Next button to get to the Start Menu dialog. Page 35
10. Provide a new folder name or accept the default as shown above. 11. Selecting the Next button will begin the installation process and present the following status dialog. 12. The following dialog is displayed when the software has been completely installed. 13. Select the Finish button to complete the installation. Page 36
2.6 LICENSE MANAGEMENT NS Discover products and solutions require a valid license in order to run. The administrator must register at the NorthRidge Software web site to download a license file. Registration is available at http://www.nridge.com/nsd-license.php Once you receive a copy of the license.properties license file, the administrator must deliver it to the configuration folder of the application service installation area. For example, if you accepted the default location to install NSD-AppService, then the folder name would be: C:\Program Files\NS\NSD-AppService\Service\cfg Page 37
3 POST INSTALLATION CONFIGURATION The following sections identify the steps required to complete the configuration of NS Discover software in order to begin use. Please note that this section uses the following convention when referring to installation folders of the software components: [NS-Home] refers to the root folder that was chosen during the installation of an NS Discover software component (e.g. NSD-AI, NSD-AppService, NSD-Search). The default example of this location would be C:\Program Files\NS. The goal of the configuration section is to educate the site administrator on the basics of configuring their Discover Innovator application. More advanced topics such as transformation pipelines, search index tuning and UI presentation updates are best handled with training classes and consulting services. Please contact our support team with any questions regarding these services. 3.1 ARAS INNOVATOR CONFIGURATION The administrator must configure Aras Innovator in order to make the Discover Innovator client available to the user from within the application. The following sections outline the steps to make the client available. 3.1.1 ADDING DISCOVER INNOVATOR ITEM TYPE A new Innovator item type must be created in order to expose Discover Innovator to the Innovator users via the TOC. 1. Log into Innovator as the administrator. 2. Navigate to Item Types below the Administration category. 3. Right click on Item Types and select New Item Type to create a New Item and populate the properties as shown below. 4. Select the TOC Access tab to identify the groups to whom you would like to provide Discover Innovator access. a. Select the icon next to the Pick Related pick list b. Search for and select one or more identities from the list that is presented. Page 38
c. By default no Category is applied. You can either select a Category under which you would like the item type to appear or leave it blank as shown below. 5. Select the TOC View tab and select the icon next to the Pick Related pick list. a. Select the identity to which you would like to provide access to the search page. b. Select the checkmark in the upper right corner to save the selection. 6. Enter the URL to the Discover Innovator page in the Start Page cell as shown below. The value should be http://hostname:8080/ns/discoverinnovator.html, where you substitute "hostname" with the host name of the machine on which you installed the NSD-AppService application service. This must be the same hostname used for the Aras Innovator server. 7. Save, unlock and close the new item. 8. Collapse the Administrator category. 9. The Discover Innovator item type should be displayed at the bottom of the TOC (or below another category if that is what you defined in step 4c). 10. Select the Discover Innovator item type to display the search page as shown below. Page 39
3.1.2 ICON IMAGES FOR RESULTS The default installation of Discover Innovator delivers the icon images for Innovator 10 or later. These icon images are referenced by the grid and snippet presentation UIs. You can register new image files by copying them to the [NS_Home]\NSD- AppService\Service\tomcat7\webapps\ns\images folder. Page 40
3.2 DISCOVER INNOVATOR CONNECTOR CONFIGURATION Discover Innovator is delivered so that it can be run directly after installation with no further configuration. Doing so will result in the connector extracting the latest version of the following item types: CAD, Document, Express ECO, Manufacturer Part, Part and Project. In addition, all files attached to Document items will have their content extracted and included in the index. Each connector provides its own configurable schema definition file that contains a collection of fields that will be populated in a document and uploaded into the search index. Details about the schema file are below. Data Source Folder: Schema File Name: [NS_Home]\NSD-AI\Service\ds ds_ai_schema.xml The schema file consists of multiple sections each delineated by an XML comment: 1. At the top of the file you will find a collection of common NS Discover fields that are prefixed with the string nsd_. These fields should not be altered or removed the configuration file. 2. The second section Aras Innovator Field Definition contain Aras Innovator fields that are prefixed with the string ai_. These fields reflect the minimum set of fields that should be available for the connector s operation. 3. The third section Required for NS Discover Common Fields and Deleted in Transformation Pipeline contain Aras Innovator fields are used for temporary purposes by the connector and later mapped to one of the nsd_ fields in the schema. 4. The final section Define Site Specific Fields Below is reserved for additional Aras Innovator fields that the site administrator would like to include in the search index. Please use this section for any new connector field definitions. 3.2.1 ADDING INNOVATOR ITEM TYPES This section will describe the steps you should follow to extend the list of Aras Innovator item types added to the search index or to update the list of fields extracted for an existing item type. 3.2.1.1 AML QUERY The Discover Innovator connector uses the Aras Markup Language (AML) to query Innovator for item information. These queries are described in a text file using an open source template language called FreeMarker. Follow these steps to create a new item type AML query file. 1. Use Windows Explorer to navigate to the [NS_Home]\NSD-AI\Service\ftl folder. 2. Copy the aml_default.ftl file to aml_<new_item_type_name>.ftl. For example, if the item type is ECO, then the destination file name would be aml_eco.ftl. Please note that you use the Name property for the item type and not a Label property. 3. Open the file new aml_eco.ftl file in a text editor. Page 41
4. Edit the item type value as shown below. a. Change <Item type='${itemtype}' to <Item type='eco' (at line 5) 5. Save the changes made in the text editor. 3.2.1.2 ITEM TYPE CRAWL REGISTRATION The Discover Innovator connector uses a crawl configuration file to identify the list of item types to process each time it executes (both full and incremental). Follow these steps to add an item type to the crawl file. 1. Use Windows Explorer to navigate to the [NS_Home]\NSD-AI\Service\cfg folder. 2. Open the crawl_start.txt file in a text editor. 3. Add ECO to the last line in the file. 4. Save the changes made in the text editor. Now you can follow the steps identified in section 3.3 to stop and start the Discover Innovator connector (NSD-AI). The connector service will wait for 2 minutes before indexing the new item types. Refer to the con_ai.log file in the [NS_HOME]\NSD- AI\Service\log folder for status about the crawl process. 3.2.2 ADDING INNOVATOR ITEM PROPERTIES There are multiple steps involved to include additional item properties in the index so that they can be used as search, filter or result fields. The four essential steps are outlined below. 1. Extract the property from Innovator to include in the index (section 3.2.2.1) 2. Update the connector schema file to include the new property (section 3.2.2.2) 3. Update the index schema to include new property (section 3.2.2.3) 4. Update the application data source for NS Discover to enable its visibility in the UI (section 3.2.2.4) If you wish to include the new properties as fields in the index for the items that are already indexed, you will need to empty the index (see section 3.5.1) and then restart the index and connector services. If the new properties are for an item type that has not already been indexed, you do not need to reset the index, but will need to stop and restart the index and connector services. 3.2.2.1 DATA EXTRACTION QUERY Please refer to the section on AML Queries (3.2.1.1) for information regarding how AML is used to query Aras Innovator. Each item type AML query is captured in a FreeMarker template file located in the [NS_Home]\NSD-AI\Service\ftl folder. Page 42
The installed Part query is formulated as follows. select= id,config_id,is_current,generation,permission_id,team_id,owned_by _id,managed_by_id,classification,item_number,major_rev,name,title,modifi ed_by_id,modified_on,current_state,keyed_name,description,created_by_id,created_on,make_buy ' The installed Document query is formulated as follows. select='id,config_id,is_current,generation,permission_id,team_id,owned_by _id,managed_by_id,classification,item_number,major_rev,name,modified_b y_id,modified_on,current_state,keyed_name,title,description,created_by_id,created_on The default query is formulated as follows. select= id,config_id,is_current,generation,permission_id,team_id,owned_by _id,managed_by_id,classification,item_number,major_rev,name,title,modifi ed_by_id,modified_on,current_state,keyed_name,description,created_by_id,created_on ' Simply add the Name value for any additional properties that you wish to include in the search index. Making this change will instruct the connector to extract these properties into the documents that will be fed into the search index. By default, the connector will rename the property value by prefixing the value with "ai_". This is an indicator that this field originated from Aras Innovator. 3.2.2.2 CONNECTOR SCHEMA FILE Please refer to the section on Discover Innovator Connector configuration (3.2) for information on how the connector schema file is structured. Follow these steps to add item properties to the connector schema file. 1. Use Windows Explorer to navigate to the [NS_Home]\NSD-AI\Service\ds folder. 2. Open the ds_ai_schema.xml file in a text editor. 3. Add a new Field entry to the last line in the file. Assuming that the property name is my_property and the data type is text, then the entry would look as follows: <Field type="text" name="ai_my_property" title="my Property" isindexed="true" isstored="true" /> 4. Save the changes made in the text editor. 3.2.2.3 INDEX SCHEMA FILE The search index uses Apache Solr to process documents and serve queries. Details about how the schema file is defined can be found here. Follow these steps to add document fields to the search schema file. Page 43
1. Use Windows Explorer to navigate to the [NS_Home]\ NSD-Search\Service\solr- 4.10.3\solr\nsdoc\conf folder. 2. Open the schema.xml file in a text editor. 3. Search for the XML comment Aras Innovator Document Field Definition (around line 152). 5. At the end of that field section (around line 177), you can add your new field entry. Assuming that the property name is my_property and the data type is text, then the entry would look as follows: <field name="ai_my_property" type="string" indexed="true" stored="true"/> 4. Save the changes made in the text editor. 3.2.2.4 APPLICATION DATA SOURCE The application service is responsible for extracting documents from the search index and transforming them for presentation in the UI. It uses a schema file that uses a field format identical to the ones used by the connectors. Follow these steps to add item properties to the application service schema file. 1. Use Windows Explorer to navigate to the [NS_Home]\NSD-AppService\Service\ds folder. 2. Open the ds_solr_nsdoc.xml file in a text editor. 3. Search for the XML comment Define Site Specific Fields Below (around line 59). 4. Add a new Field entry to the last line in the file. Assuming that the property name is my_property and the data type is text, then the entry would look as follows: <Field type="text" name="ai_my_property" title="my Property /> 5. Save the changes made in the text editor. 3.2.2.5 UI SNIPPET PRESENTATION The application service is also responsible for presenting documents extracted from the search index to the user via a web browser UI. There are several files related to the UI presentation layer and they are identified below for completeness. Snippet UI Presentation Files [NS_Home]\NSD-AppService\Service\tomcat7\webapps\ns\WEB-INF\classes\di_snippet_child.ftl [NS_Home]\NSD-AppService\Service\tomcat7\webapps\ns\WEB-INF\classes \di_snippet_parent.ftl Grid UI Presentation Files [NS_Home]\NSD-AppService\Service\tomcat7\webapps\ns\ds\diResult.ds [NS_Home]\NSD-AppService\Service\tomcat7\webapps\ns\ds\diDetail.ds Search Form Presentation File [NS_Home]\NSD-AppService\Service\tomcat7\webapps\ns\ds\diSearch.ds Page 44
3.3 STARTING SERVICES After all the software has been installed and the post-installation configuration changes completed, the services for the search, application and connector services must be started. 3.3.1 SEARCH SERVICE The NSD-Search service is accessible via the Windows Services dialog as displayed below. Use the Start and Stop actions to control the operation of the service. By default, this service is configured to start automatically on reboot. The NSD-Search service should be started before the NSD-AppService and individual connectors. 3.3.2 APPLICATION SERVICE The NSD-AppService service is accessible via the Windows Services dialog as displayed below. Page 45
Use the Start and Stop actions to control the operation of the service. By default, this service is configured to start automatically on reboot. The NSD-AppService service should be started before the individual connectors. 3.3.3 CONNECTOR SERVICES The NSD-AI, NSD-FS and NSD-WS services are accessible via the Windows Services dialog as displayed below. Use the Start and Stop actions to control the operation of each service. By default, these services are configured to start automatically on reboot. The NSD-Search and NSD- AppService services should be started before these connectors. Please refer to section 3.2 for configuration information before starting the connector service. Page 46
3.4 DISCOVER INNOVATOR EMAIL CONFIGURATION Email notifications can be generated when the NSD-AI connector service detects them. This feature can be enabled by configuring the email properties in the application.properties file as described in the following table. Property Description connector.ai.mail.delivery_enabled Set this value to true to enable email notification connector.ai.mail.smtp_host Qualified name of the SMTP host (i.e. smtp.nridge.com) connector.ai.mail.smtp_port SMTP port number. Default is 25. connector.ai.mail.authn_enabled This value should be set to true. connector.ai.mail.account_name The email account name (i.e. username@nridge.com) that will connect to the mail server. connector.ai.mail.account_password The password of the email account name user. connector.ai.mail.address_to The email address of the user to whom the email notifications will be sent. Multiple accounts, separated by commas, can be included. connector.ai.mail.address_from The email address of the user from which the email notifications will be sent. connector.ai.mail.template_service_file The name of the file in the NSD-AI\Service\cfg folder that will serve as the email template. The default is email_error_message.ftl. Page 47
3.5 RESET SEARCH INDEX & FULL CONNECTOR CRAWL Some configuration changes will require you to reset (empty) the index and execute a full crawl with the Discover Innovator connector. This is typically the case when you have changed the search schema for documents that are already included in the index and you wish to update the documents to include the fields from the new definition. 3.5.1 RESET THE SEARCH INDEX Follow these steps to empty the search index of all its documents. Once these steps are complete, the search index will be empty and will not return documents in a query until a new connector crawl redelivers them. 1. Stop the NSD-AI connector service from the Windows Services dialog window. 2. Open a web browser window and type the following in the address bar. http://<hostname>:8511/admin/reset?confirm=yes Where <hostname> refers to the server machine where the NSD-AppService was installed. The following message will be displayed within the web browser web page confirming the reset operation. Discover Application Service - Release 4.0 The data source repositories have been successfully reset. 3.5.2 EXECUTE FULL CONNECTOR CRAWL Follow these steps to force the re-crawling of all Aras Innovator content in the search index. Upon a successful reset of the search index, you must set your environment so that a full feed can be executed. 1. Stop the NSD-AI connector service from the Windows Services dialog window. 2. Navigate to the [NS-HOME]\NSD-AI\Service\log folder. 3. Delete the service-tracker.xml file. 4. Start the NSD-AI connector service from the Windows Services dialog window. A full connector crawl will start in 2 minutes and begin the process of uploading documents into the search index. Page 48
4 TROUBLESHOOTING This section provides the Administrator with guidance on how to work around issues that may occur during the installation, configuration or operation of NorthRidge Discover and its products. 4.1 CLIENT ERRORS The following issues may prevent the connector from operating correctly unless corrected. 4.1.1 CLIENT GENERATES LICENSE ERROR Each Connector requires a valid license in order to feed content from its source to the Index Server. License failures can occur if the license file is not present in the [NS_HOME]\NSD- AppService\Service\tomcat7\webapps\ns\WEB-INF\classes folder or the license file is invalid. 4.1.2 LOGIN DIALOG APPEARS NEEDING USERNAME AND PASSWORD Discover Innovator will not authenticate automatically under the following conditions. You are not using an IE browser You did not install NSD-AppService on the same server where the Aras Innovator service is running The hostname in the URL that you are using to launch Discover Innovator is not the same hostname used in the URL to launch Aras Innovator 4.1.3 PRINT BUTTON INACTIVE After deploying Discover Innovator in a distributed environment, if you experience that the Print button in the function toolbar is non-responsive, it may be a result of using a fully qualified domain name (FQDN) in the URL that launches Discover Innovator rather than just the host name. For example, we have seen the following URL prevent the Print feature from working properly. http://server.company.com:8080/ns/discoverinnovator.html However, a non FQDN URL does not appear to impact the Print feature. http://server:8080/ns/discoverinnovator.html We have an issue report submitted with the UI widget vendor that we use. In the meantime, you can use the new Export feature to generate a spreadsheet of results for printing. 4.2 CONNECTOR ISSUES 4.2.1 INCREMENTAL FEEDS NOT PROCESSING Page 49
Deployments where Innovator has been configured to utilize Corporate Time rather than Local Time may not correctly process incremental feeds. The Discover Innovator Connector provides a configuration property that can reconcile the difference between Local Time and Corporate Time. The steps below will help you to identify the value that must be assigned to the configuration property. 1. Log into the machine where NSD-AI Connector was installed and note the system time. 2. For that same time, note the Corporate Time for the Innovator server. This may be displayed on the client as shown below. 3. Subtract the Connector Time from the Corporate Time and document that value. You need only focus on the difference in hours. 4. Stop the NSD-AI connector service from the Windows Services dialog window. 5. Edit the [NS_HOME]\NSD-AI\Service\cfg\application.properties file. 6. Set the value of connector.ai.extract.server_time_hour_delta to the value calculated in step 3. a. Make sure you set it to a negative value if that is what was calculated. 7. Save the [NS_HOME]\NSD-AI\Service\cfg\application.properties file. 8. Start the NSD-AI connector service from the Windows Services dialog window. Examples Corporate Time Connector Time Offset 10:00 AM 8:00 AM 2 7:00 AM 11:00 AM -4 Items that were not indexed from the last full crawl up until the incremental crawl time should now be processed. 4.3 APPLICATION SERVICE ISSUES 4.3.1 ENABLING VERBOSE LOGGING LEVELS If you are experiencing connection issues with the Application Service, then you can follow these steps to enable a verbose logging level. 1. Edit the [NS_HOME]\NSD-AppService\Service\cfg\logback.xml file. 2. Locate the commented out section starting at line 20 in the file. Page 50
3. Uncomment the section so that it looks as follows. Page 51
4. Save the file. 5. Stop the NSD-AppService service from the Windows Services dialog window. 6. Navigate to the [NS-HOME]\NSD-AppService\Service\log folder. 7. Remove any existing log files. Page 52