Coveo Platform 7.0. OpenText Content Server Connector Guide

Transcription

1 Coveo Platform 7.0 OpenText Content Server Connector Guide

2 Notice The content in this document represents the current view of Coveo as of the date of publication. Because Coveo continually responds to changing market conditions, information in this document is subject to change without notice. For the latest documentation, visit our website at Coveo Solutions Inc., 2013 Coveo is a trademark of Coveo Solutions Inc. This document is protected by intellectual property laws and is subject to all restrictions specified in the Coveo Customer Agreement. Document part number: PM EN Publication date: 5/14/2018 4www.coveo.com ii

3 Table of Contents 1. OpenText Content Server Connector 1 2. OpenText Content Server Connector Deployment Overview 4 3. OpenText Content Server Connector Requirements 6 4. Enabling the OpenText Content Server Web Services Connecting the OTCS Web Services Setting IIS Permissions Enabling WCF Services 9 5. Setting Up an OpenText Content Server Crawling Account Configuring an OpenText Content Server Security Provider Configuring and Indexing an OpenText Content Server Source Creating an OpenText Content Server Connector Mapping File Standard Mapping File Schema Modifying Hidden OpenText Content Server Source Parameters Adding an Explicit Connector Parameter Managing Built-in Facets and Related Results Appearing in a.net Search Interface Adding Security Providers to a.net Search Interface 39 4www.coveo.com iii

4 4www.coveo.com iv

5 1. OpenText Content Server Connector CES (April 2013) The Coveo connector for OpenText Content Server (OTCS) allows you to crawl and bring OTCS content into the unified index, making it easily searchable by end-users. Note: OpenText Content Server is a technology component that was formerly known as Livelink ECM - Enterprise Server (see the OpenText document Livelink is Now Part of the OpenText ECM Suite). Connector Features Content indexing The connector can retrieve and index exclusively the following default OTCS entity types: Appearance Workspace Folder Appearance Category Channel Collection (without the children documents) Compound Document Discussion Document Enterprise Workspace Folder Live Report News Poll Project Prospector Reply Shortcut Task List Task Topic 4www.coveo.com 1

6 URL Virtual Folder Workflow Status XML DTD Fully supported security model The connector fully supports the OTCS security model using a security provider to get permissions for each indexed OTCS item. This means that, in Coveo search interfaces, a user searching for OTCS content only sees the content to which he has access in OTCS. Incremental refresh CES (May 2013) The incremental refresh feature continuously and automatically refreshes indexed OTCS items as they are modified. Notes: CES (September 2016) The incremental refresh can take account of deleted items (except news items) that are stored in the Recycle Bin module. A source full refresh or rebuild is required to update deleted news items since news are not in the Recycle Bin once deleted. Incremental refresh limitations: o o o o o A source full refresh or rebuild is required to update added and modified items in projects, channels, discussions, and task lists (child items). A source full refresh or rebuild is required to update child items permissions when the parent item is modified. Takes into account deleted items only if the OpenText Content Server Recycle Bin module is enabled in OTCS, but with CES (Dec 2015), a source full refresh or rebuild is required to remove deleted items. CES (June 2016) Incremental refreshes are supported even if the Document Undelete module is not installed. However, when the module is not installed, deleted items (except documents) are not taken into account. Not available for Livelink sources. Connector Feature History Coveo Platform version Monthly release Features March 2016 Add support for OTCS www.coveo.com 2

7 Coveo Platform version Monthly release Features May 2013 Add incremental refresh for OTCS Add support for Livelink April 2013 Introduction of the connector What's Next? Review the deployment process (see "OpenText Content Server Connector Deployment Overview" on page 4). 4www.coveo.com 3

8 2. OpenText Content Server Connector Deployment Overview The following procedure outlines the steps needed to deploy the OpenText Content Server (OTCS) connector. The steps indicate the order in which you must perform configuration tasks on both the OTCS and Coveo servers. To deploy the OpenText Content Server connector 1. Validate that your environment meets the requirements (see "OpenText Content Server Connector Requirements" on page 6). 2. In OpenText Content Server: a. Enable the Web Services. The Coveo connector requires OTCS Web services to operate. You must ensure that these Web services are available (see "Enabling the OpenText Content Server Web Services" on page 7). b. Select or create the crawling account. The Coveo connector needs an OTCS account with which it can fully crawl the OTCS content (see "Setting Up an OpenText Content Server Crawling Account" on page 10). 3. In the Coveo Administration Tool: a. Configure a user identity. The Coveo connector needs to know the OTCS account that you previously selected or created. You must create a CES user identity to use this account. Use either the Screen Name or the Address of the dedicated OTCS account. You will later assign this user identity to the security provider and the source used by the connector to crawl the OTCS content. b. Configure a security provider. The Coveo connector needs a security provider to be able to get the permissions for each indexed OTCS item, and therefore fully support the OTCS security model (see "Configuring an OpenText Content Server Security Provider" on page 13). c. Configure and index the OpenText Content Server source. The Coveo connector needs to know details about OTCS to be able to index its content (see "Configuring and Indexing an OpenText Content Server Source" on page 16). 4. Enrich your OTCS indexed content a. Optionally, create and use a mapping file to fine-tune indexed content Consider customizing the connector mapping file to fine-tune the indexed content or to index other entities in your OTCS (see "Creating an OpenText Content Server Connector Mapping File" on page 22). b. Optionally, modify hidden source parameters. 4www.coveo.com 4

9 Once your OTCS source is up and running, if you encounter issues, consider modifying some hidden source parameters to try resolving the issues (see "Modifying Hidden OpenText Content Server Source Parameters" on page 29). 5. Customize your search interfaces with OTCS content a. Add OTCS facets to your search interfaces You can create facets using fields such as the OTCSFileType metadata to allow users to easily filter OTCS documents (see "Managing Built-in Facets and Related Results Appearing in a.net Search Interface" on page 36). b. Allow OTCS users to be authenticated in a Coveo search interface When your OTCS is not integrated with Active Directory, your end-users need to sign in to OTCS in a Coveo search interface to be able to see search results from OTCS. In this case, you need to add the OTCS security provider to your search interface to allow end-user to sign in to OTCS (see "Adding Security Providers to a.net Search Interface" on page 39). 4www.coveo.com 5

10 3. OpenText Content Server Connector Requirements Your environment must meet the following requirements to be able to use the Coveo connector for OpenText Content Server: CES (April 2013) Coveo license for the OpenText Content Server connector Your Coveo license must include support for the OpenText Content Server connector to be able to use this connector. OpenText product support: o OpenText Content Server (OTCS) 10.5 Note: CES (March 2016) Support for OTCS o Deprecated support versions: Livelink CES (May 2013) and OTCS 10 What's Next? The Coveo connector for OpenText Content Server (OTCS) needs OpenText Web services to be able to index OTCS content (see "Enabling the OpenText Content Server Web Services" on page 7). 4www.coveo.com 6

11 4. Enabling the OpenText Content Server Web Services The Coveo connector for OpenText Content Server (OTCS) needs OpenText Web services to be able to index OTCS content. The files for the required web services are installed with the OTCS installation. Use the following procedures to correctly connect, configure, and set permissions for OTCS Web services: "Connecting the OTCS Web Services" on page 7 "Setting IIS Permissions" on page 8 "Enabling WCF Services " on page Connecting the OTCS Web Services 1. Using an administrator account, connect to your OTCS server. 2. Start Internet Information Services (IIS) Manager. 3. On the Internet Information Services (IIS) Manager left pane, expand your server > Sites. 4. If not already done when you installed OTCS, right-click Default Web Site, and then select Add Application in the menu, and in the Add Application dialog box: 4www.coveo.com 7

12 a. In the Alias box, enter les-services or cws (OTCS 10.5+). b. In the Physical path box, enter C:\OPENTEXT\webservices\dotnet\les-services or C:\OPENTEXT\webservices\dotnet\cws (OTCS 10.5+). c. Click OK. Note: The Coveo connector needs the following OTCS web services that are installed by default in the C:\OPENTEXT\webservices\dotnet\les-services (C:\OPENTEXT\webservices\dotnet\cws for OTCS 10.5+) folder: Authentication DocumentManagement IndexService MemberService ContentService 5. Back on the Internet Information Services (IIS) Manager left pane, click your new les-services or cws (OTCS 10.5+) application. 6. On the right pane, click Advanced Settings and in the Advanced Settings dialog box: a. In Application Pool, select ASP.NET 2.0. b. Click OK. 7. Still with new les-services or cws(otcs 10.5+)application selected, in the central pane, double-click Handler Mappings. 8. On the right pane, click Edit Feature Permissions and in the Edit Feature Permissions dialog box: a. Select the Read and Script check boxes. b. Click OK. 4.2 Setting IIS Permissions 1. On the OTCS server, using Windows Explorer, navigate to the [OT_HOME]\webservices\dotnet folder. 2. Right-click the les-services or cws (OTCS 10.5+)folder, and then choose Properties. 3. In the les-services Properties or cws Properties (OTCS 10.5+) dialog box: a. Select the Security tab. b. Under Group or user names, click Edit. c. In the Permissions for les-services or Permissions for cws (OTCS 10.5+) dialog box: 4www.coveo.com 8

13 i. Add the local IUSR user with the Read permissions. ii. iii. Add the IIS Application Pool Identity (e.g. ApplicationPoolIdentity or NetworkService) with Read & execute permission. Click OK. d. Click OK. 4. In the Windows Explorer, open the [OT_HOME]\webservices\dotnet\les-services or [OT_ HOME]\webservices\dotnet\cws (OTCS 10.5+) folder. 5. Right-click the logs folder, and then choose Properties. 6. In the logs Properties dialog box: a. Select the Security tab. b. Under Group or user names, click Edit. c. In the Permissions for logs dialog box: i. For the IIS Application Pool Identity (e.g. ApplicationPoolIdentity or NetworkService) select the Modify permission. ii. Click OK. d. Click OK. 4.3 Enabling WCF Services 1. On the OTCS server, open a Command Prompt window (cmd.exe). 2. Execute the following command to enable the WCF Services: "%SystemRoot%\Microsoft.NET\Framework\v3.0\Windows Communication Foundation\ServiceModelReg.exe" -i 3. When the command completes, close the Command Prompt window. What's Next? Select or create an OTCS crawling account to be used by the Coveo connector to fully crawl the OTCS content (see "Setting Up an OpenText Content Server Crawling Account" on page 10). 4www.coveo.com 9

14 5. Setting Up an OpenText Content Server Crawling Account The Coveo connector needs to connect to the OpenText Content Server (OTCS) using an account that has read access to all the OTCS content that you want to index. The Coveo connector only reads and does not modify the OTCS content. The best practice is to create an OTCS crawling account with a non-expiring password to be used exclusively by the Coveo connector and grant this account complete read access to all OTCS content. When you want to also index permissions, the crawling account requires System administration rights. To grant the crawling account read permissions to all items 1. Using an administrator account, sign in to OpenText ECM Suite. 2. On the OpenText Content Server menu, select Enterprise > Workspace. 3. Next to Enterprise, click the Functions arrow, and in the menu, select Permissions. 4. In the Permissions page: 4www.coveo.com 10

15 a. In the Assigned Access section, add the crawling account to which you want to grant the rights. b. Click the newly created crawling account, and in the Edit User Permissions pane: i. Select the See Contents check box. ii. iii. iv. In the Apply To drop-down list, select This item & sub-items. In the Sub-Items Options, select the check boxes for item types that you want to index. Click Update. To grant the crawling account System Administration Rights 1. Using an administrator account, sign in to OpenText ECM Suite. 2. On the OpenText Content Server menu, select Enterprise > Users & Groups. 3. In the Users and Groups page, find the user to which you want to grant Administration rights, and then click the 4www.coveo.com 11

16 Edit link for that user. 4. In the General Info for: [username] page: a. Select the General tab. b. In the Privileges section at the bottom, select the System administration rights check box. c. Click Update. What's Next? On the Coveo server, configure a CES user identity for your OTCS crawling account and then create a security provider (see "Configuring an OpenText Content Server Security Provider" on page 13). 4www.coveo.com 12

17 6. Configuring an OpenText Content Server Security Provider The Coveo connector needs a security provider to be able to get the permissions for each indexed OpenText Content Server (OTCS) item, and therefore fully support the OTCS security model. This means that, in a Coveo search interface, a user searching for OTCS content only sees the content to which he has access in OTCS. Note: You can get familiar with how Coveo components deal with permissions on documents both at indexing and query time. To configure a OpenText Content Server security provider 1. On the Coveo server, access the Administration Tool. 2. Select Configuration > Security. 3. In the Security page, in the navigation panel on the left, click Security Providers. 4. In the Security Providers page, click Add to create a new security provider. 5. In the Modify Security Provider page: 4www.coveo.com 13

18 a. In the Name box, enter a name to identify this security provider. Example: OpenText Content Server Security Provider Note: You can also use the OTCS connector to crawl a Livelink version source. You need to add a hidden parameter to do so (see below). b. In the Security Provider Type drop-down list, select OpenText Content Server (x64). c. In the User Identity section: i. In the drop-down list, select the user identity that you selected or created previously. ii. When needed, click Add, Edit, or Manage user identities respectively to create, modify, or manage user identities. d. CES (June 2013) In the Security Provider for User Mappings drop-down list, select the security provider that will receive the login names of the users and perform the mapping to OTCS users. Example: When Microsoft Windows users perform a search, select an Active Directory security provider to map AD users to OTCS users. e. In the Web Service Url box, enter the address of the OpenText Content Server Web Service. By default, this value is: where you replace OTCS_Server by the fully qualified domain name of your server. Example: Important: CES (March 2016) (For OTCS only) Replace les-services by cws. Example: Note: You will also need to specify this URL in the Web Service URL parameter when you configure your source (see "Configuring and Indexing an OpenText Content Server Source" on page 16). f. In the Web Service Configuration File box, in rare cases where the security provider encounters communication issues with Windows Communication Foundation (WCF), you can modify the way in which the security provider communicates with OTCS by entering the path and file name of a custom configuration file (see the Microsoft document Configuring Services Using Configuration Files). g. Next to Parameters, click Add Parameter when you want to show and use advanced source parameters (see "Modifying Hidden OpenText Content Server Source Parameters" on page 29). Important: CES (May 2013) When you are indexing a Livelink v9.7.1, you must add the OTCSVersion parameter and enter the value. h. Leave the Allow Complex Identities option cleared as it does not apply to this type of security provider. i. Click Apply Changes. 4www.coveo.com 14

19 What's Next? Configure and index an OTCS source (see "Configuring and Indexing an OpenText Content Server Source" on page 16). 4www.coveo.com 15

20 7. Configuring and Indexing an OpenText Content Server Source A source defines a set of configuration parameters for a specific OpenText Content Server (OTCS). Note: In an environment with more than one OTCS, you need to define one source for each OTCS that you want to index. To configure and index an OpenText Content Server source 1. On the Coveo server, access the Administration Tool. 2. Select Index > Sources and Collections. 3. In the Collections section: a. Select an existing collection in which you want to add the new source. OR b. Click Add to create a new collection. 4. In the Sources section, click Add. The Add Source page that appears is organized in three sections. 5. In the General Settings section of the Add Source page: 4www.coveo.com 16

21 a. Enter the appropriate value for the following required parameters: Name Enter a descriptive name of your choice for the connector source. Example: OpenText Content Server Source Type Select the connector used by this source. In this case, select OpenText Content Server. Notes: If you do not see OpenText Content Server, your environment does not meet the requirements (see "OpenText Content Server Connector Requirements" on page 6). You can also use the OTCS connector to crawl a Livelink version source. You need to add a hidden parameter to do so (see below). Addresses Enter the document or folder IDs that you want to index. One ID per line or * to index the whole OTCS content from the Enterprise Workspace root. Note: CES (July 2014) This parameter is not used for the OpenText Content Server connector, but must not be left empty. Enter NA. You can find the ID for a node in OTCS by clicking the Functions icon of an item, selecting Properties > General on the menu, clicking Change next to Nickname, and then read the Item ID value. Example: When you want to create an OTCS source only for one project, in the project General property tab, read the Item ID value, like 4094 in the following example. 4www.coveo.com 17

22 Note: Using certain item types as the root node will result in an error when retrieving their permissions. All item types receiving their permissions from their parents (such as Task, News, all types under Discussion, and possibly other types) are not supported as the root node. Refresh Schedule Time interval at which the source is automatically refreshed to keep the index content up-to-date. The recommended Every day option instructs CES to refresh the source everyday at 12 AM. Note: You can create new or modify existing source refresh schedules. b. Review the value for the following parameters that often do not need to be modified: Rating Change this value only when you want to globally change the rating associated with all items in this source relative to the rating to other sources. Example: When a source replaces a legacy system, you may want to set this parameter to High, so that in the search interface, results from this source appear earlier in the list compared to those from legacy system sources. Document Types If you defined a custom document type set for this source, select it. Active Languages If you defined custom active language sets, ensure to select the most appropriate for this source. Fields By default, when an OTCS metadata name matches the name of a CES standard or custom field, the metadata value is automatically mapped to the CES field and the field can be used to make the search interface results more relevant. It is a good practice to create a custom field set that and fields with names matching those of your signification OTCS metadata. If you defined custom field sets, ensure to select the most appropriate for this source. 6. In the Specific Connector Parameters & Options section of the Add Source page: 4www.coveo.com 18

23 a. Configure the following required parameters: Web Service URL Enter the URL of the OpenText Content Server Web Service used to communicate with the server. By default, this value is: where you replace OTCS_Server by the fully qualified domain name of your server. Example: Important: CES (March 2016) (For OTCS only) Replace les-services by cws. Example: Note: This is the same value that you entered for the Web Service Url parameter when you configured the security provider (see "Configuring an OpenText Content Server Security Provider" on page 13). Content Server URL Enter the URL pointing to the OpenText Content Server necessary to have valid clickable URIs. Example: When you access the OTCS, the Content Server URL is the part of the URL before Livelink.exe: In the above example: 4www.coveo.com 19

24 b. Review the value for the following parameters that often do not need to be modified: Mapping File By default, when an OTCS metadata name matches the name of a CES standard or custom field, the metadata value is automatically mapped to the CES field. When this default behavior is sufficient to leverage OTCS metadata, leave this field empty. When you want to control more precisely how to map OTCS metadata to CES fields, create a custom mapping file and enter the absolute full path pointing to your file (see "Creating an OpenText Content Server Connector Mapping File" on page 22). Example: C:\CES7\Config\MyOTCSMappingFile.xml Number of Refresh Threads Enter the number of threads that will be used to retrieve OpenText Content Server content. The default value is 2. Parameters Click Add Parameter when you want to show and use advanced source parameters (see "Modifying Hidden OpenText Content Server Source Parameters" on page 29). Important: CES (May 2013) When you are indexing a Livelink v9.7.1, you must add the OTCSVersion parameter and enter the value. c. In the Option section: Index Subfolders Keep this check box selected (recommended). By doing so, all subfolders from the specified portal address are indexed. Index the document's metadata When selected, CES indexes all the document metadata, even metadata that are not associated with a field. The orphan metadata are added to the body of the document so that they can be searched using free text queries. When cleared (default), only the values of system and custom fields that have the Free Text Queries attribute selected will be searchable without using a field query. 4www.coveo.com 20

25 Example: A document has two metadata: LastEditedBy containing the value Hector Smith Department containing the value RH In CES, the custom field CorpDepartment is bound to the metadata Department and its Free Text Queries attribute is selected. When the Index the document's metadata option is cleared, searching for RH returns the document because a field is indexing this value. Searching for hector does not return the document because no field is indexing this value. When the Index the document's metadata option is selected, searching for hector also returns the document because CES indexed orphan metadata. Document's addresses are case-sensitive Leave the check box cleared. This parameter needs to be checked only in rare cases for systems in which distinct documents may have the same name but different casing. Generate a cached HTML version of indexed documents When you select this check box (recommended), at indexing time, CES creates HTML versions of indexed documents. In the search interfaces, users can then more rapidly review the content by clicking the Quick View link rather than opening the original document with the original application. Consider clearing this check box only when you do not want to use Quick View links or to save resources when building the source. Open results with cached version Leave this check box cleared (recommended) so that in the search interfaces, the main search result link opens the original document with the original application. Consider selecting this check box only when you do not want users to be able to open the original document but only see the HTML version of the document as a Quick View. In this case, you must also select Generate a cached HTML version of indexed documents. 7. In the Security section of the Add Source page: 4www.coveo.com 21

26 a. In the OpenText Content Server Security Provider drop-down list, select the security provider that you created for this source (see "Configuring an OpenText Content Server Security Provider" on page 13). b. In the Authentication drop-down list, select the user identity that you created for the OpenText Content Server. c. Click Save and Start to save the source configuration and start indexing this source. 8. Validate that the source building process is executed without errors: In the navigation panel on the left, click Status, and then validate that the indexing proceeds without errors. OR Open the CES Console to monitor the source building activities. What's Next? Set an incremental refresh schedule for your source. If you experience issues or want to fine tune how your OTCS source is indexed, consider using hidden OTCS source parameters (see "Modifying Hidden OpenText Content Server Source Parameters" on page 29). 7.1 Creating an OpenText Content Server Connector Mapping File The Coveo connector for OpenText Content Server (OTCS) has no mapping file by default. When the name of metadata found on OTCS documents matches the name of CES system or custom fields, the metadata are automatically mapped. When you need to more accurately control where and how metadata is mapped on your items, you must create and use a mapping file that respects the schema of the standard mapping file (see "Standard Mapping File Schema" on page 23). Examples: You need a mapping when you want to: Customize the HTML body for items of a specific type. Concatenate two or more OTCS metadata in a CES field. Map an OTCS metadata value to a CES field for which names do not match. To create and use an OTCS connector mapping file 1. Using an administrator account, connect to the Coveo Master server. 2. Using a text editor: a. Create the mapping file. You can start with the following commented sample mapping file. <?xml version="1.0" encoding="utf-8"?> <Mappings><!-- Review the ValidationSchemaVersion1.xsd to view the available fields and attributes --> 4www.coveo.com 22

27 <Version>1</Version><!-- Mandatory node to identify the mapping file version. Do not modify. --> <CommonMapping><!-- Optional. Any Mapping defined within this section will be applied to all documents. --> <Title>%[title]</Title> </CommonMapping> <Mapping type="document"><!-- Optional. This is a specific mapping. The fields and elements described will only be applied to items of type "Document". Values for OpenText Content Server are the type of nodes. -- > <Body>This is a body</body> <PrintableUri> <Fields> <Field name="field1">%[metadata1]</field> </Fields> </Mapping> <DefaultMapping> <!-- Optional. This is the default mapping. It will be applied to any item that was not mapped to a specified mapping --> <ClickableUri> </DefaultMapping> </Mappings> b. Respecting the mapping file format, customize the file using the following tips: Use OTCS node types to create specific <Mapping type="..."> tags in the mapping file. You can easily find the values to enter in this tag from the Type of items in OpenText Content Server. Example: When you want to manage OTCS Discussion fields, in the OTCS Workspace, simply hover a discussion item. The tooltip indicates the value to enter in the Mapping type tag. In the mapping file, you would create the <Mapping type="discussion"> node. The connector populates the special OTCSFileType metadata with the type of OTCS documents. This metadata is useful to create a facet based on the types of items found in OTCS. c. Save the file using a name of your choice in the [Index_Path]\Config\ folder. d. Save your changes. What's Next? Assign your customized mapping file in your OpenText Content Server source (see "Configuring and Indexing an OpenText Content Server Source" on page 16). 7.2 Standard Mapping File Schema A Coveo connector may need a mapping file to correctly copy the repository metadata values to appropriate index fields. This topic describes the format of the standard mapping file by providing its XML schema definition. Refer to this schema to review the possible content of the file and ensure that your mapping file is valid. 4www.coveo.com 23

28 Notes: CES (October 2015) Using a mapping file, in a field or body element, you can retrieve the content of an external file by setting the isurl attribute to true in the start tag and entering the external file URL as the value. Example: <Field name="contact" isurl="true">%[urlmetadata]</field> The normal mapping resolution is performed and when the download attempt of the resolved value is successful, the downloaded content is converted to a string and put in the body or field element. One use case is when you have a database with a column containing a URI that points to a document that you want to use as a body. When using this feature, have in mind that: o o o o o o isurl is case-sensitive. Direct mapping (ex: <Field name="[value]" isurl="true">[value]</field>) and mapping resolution (ex: <Body isurl="true">%[file_path_or_url]</body>) are both supported schemes. Old mappings are compatible, meaning that when isurl is not specified, the attribute is considered set to false (no download is performed). The specified external file can be a.pdf,.docs,.etc,.txt,. RTF or.html file and its URL can start with or file://. The content of the external file must be public since no authentication is supported when performing the download attempt. When an invalid URL is specified, an error message stating that a mapping fails is logged, but the document is still indexed. By default, when the name of a field in the field set selected for the source matches the name of a metadata from the indexed repository, the metadata value is automatically copied to the field, even when they are not formally associated in a mapping file. The standard mapping file schema is supported by all connectors written in C# (all connectors except Web Legacy). However, it is recommenced for the connectors that use their own mappings (such as Oracle UCM) to NOT mix these specific mappings with standard ones. Some connectors come with a default mapping file that is available in the [CES_Path]\bin folder, The mapping file name is in the form: Coveo.CES.CustomCrawlers.[ConnectorName].MappingFile.xml When a default mapping file is available, it is recommended to start with its content by using and customizing a copy of the file. This mapping file format is used by more recently developed or updated connectors. This standard mapping file only contains metadata to field mappings, not other connector configuration parameters. When needed, a connector rather uses a separate configuration file for non-mapping parameters. The format of the mapping file version 1 is specified in the following XML schema definition (XSD). 4www.coveo.com 24

29 <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" <!-- definition of possible elements --> <xs:element name="mappings"> <xs:complextype> <xs:sequence> <xs:element name="version" minoccurs="1" maxoccurs ="1" /> <xs:element name="commonmapping" type="genericmapping" minoccurs="0" maxoccurs ="1"/> <xs:element name="mapping" type="specificmapping" minoccurs="0" maxoccurs ="unbounded"/> <xs:element name="defaultmapping" type="genericmapping" minoccurs ="0" maxoccurs="1"/> </xs:sequence> </xs:complextype> <xs:unique name="mappings"> <xs:selector xpath="mapping"/> <xs:field </xs:unique> </xs:element> <!-- definition of generic (common and default) mapping section --> <xs:complextype name="genericmapping"> <xs:group ref="mappingelement" /> </xs:complextype> <!-- definition of a specific mapping section --> <xs:complextype name ="SpecificMapping"> <xs:group ref="mappingelement" /> <xs:attribute name="type" use=" required" /> </xs:complextype> <!-- definition of a mapping element.--> <xs:group name="mappingelement"> <xs:all> <xs:element name ="Title" minoccurs="0" maxoccurs = "1"/> <xs:element name="body" minoccurs="0" maxoccurs = "1"/> <xs:element name="clickableuri" minoccurs="0" maxoccurs = "1"/> <xs:element name="printableuri" minoccurs="0" maxoccurs = "1"/> <xs:element ref="fields" minoccurs="0" maxoccurs = "1"/> </xs:all> </xs:group> <!-- definition of fields element --> <xs:element name="fields"> <xs:complextype> <xs:sequence> <xs:element ref="field" minoccurs="0" maxoccurs = "unbounded"/> </xs:sequence> </xs:complextype> <xs:unique name="field"> <xs:selector xpath="field"/> <xs:field xpath="@name"/> </xs:unique> </xs:element> <!-- definition of field element --> <xs:element name="field"> <xs:complextype> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute name="name" use="required"/> </xs:extension> </xs:simplecontent> </xs:complextype> </xs:element> </xs:schema> 4www.coveo.com 25

30 Example: The JIVE connector uses the standard mapping file schema: <?xml version="1.0" encoding="utf-8"?> <Mappings> <Version>1</Version> <CommonMapping> <Fields> <Field name="sysauthor">%[author.displayname]</field> <!-- Jive system fields --> <Field name="syscstag">%[tags]</field> <Field name="syscstaggroup">%[categories]</field> <Field name="syscsplace">%[coveo.places.titles]</field> <Field name="syscsplacetype">%[coveo.places.types]</field> </Fields> </CommonMapping> <Mapping type="announcement"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csannouncement</field> <!-- Jive system fields --> <Field name="syscsitemtype">announcement</field> </Fields> </Mapping> <Mapping type="attachment"> <Title>%[name]</Title> <Fields> <Field name="sysfilename">%[name]</field> </Fields> </Mapping> <Mapping type="checkpoint"> <Title>%[name]</Title> <Body>%[description]</Body> <Fields> <Field name="sysdtdue">duedate</field> <Field name="sysfiletype">cscheckpoint</field> <!-- Jive system fields --> <Field name="syscsitemtype">checkpoint</field> </Fields> </Mapping> <Mapping type="comment"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">cscomment</field> <!-- Jive system fields --> <Field name="syscsitemtype">comment</field> </Fields> </Mapping> <Mapping type="discussion"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csdiscussion</field> <!-- Jive system fields --> <Field name="syscsitemtype">discussion</field> </Fields> </Mapping> <Mapping type="dm"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csdm</field> <!-- Jive system fields --> <Field name="syscsitemtype">dm</field> </Fields> </Mapping> <Mapping type="document"> 4www.coveo.com 26

31 <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfilename">%[subject]</field> <Field name="sysfiletype">csdocument</field> <!-- Jive system fields --> <Field name="syscsitemtype">document</field> </Fields> </Mapping> <Mapping type="file"> <Title>%[subject]</Title> <Fields> <Field name="sysfilename">%[subject]</field> </Fields> </Mapping> <Mapping type="group"> <Title>%[name]</Title> <Body>%[description]</Body> <Fields> <Field name="sysauthor">%[creator.displayname]</field> <Field name="sysfiletype">cssocialgroup</field> <!-- Jive system fields --> <Field name="syscsitemtype">social Group</Field> </Fields> </Mapping> <Mapping type="idea"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csidea</field> <!-- Jive system fields --> <Field name="syscsitemtype">idea</field> </Fields> </Mapping> <Mapping type="message"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csmessage</field> <!-- Jive system fields --> <Field name="syscsitemtype">message</field> </Fields> </Mapping> <Mapping type="person"> <Title>%[displayName]</Title> <Body> %[displayname] %[ s(work).value] %[jive.profile(title).value]</body> <Fields> <Field name="userprofile_firstname">%[name.givenname]</field> <Field name="userprofile_lastname">%[name.familyname]</field> <Field name="userprofile_accountname">%[jive.username]</field> <Field name="userprofile_title">%[jive.profile(title).value]</field> <Field name="userprofile_aboutme">%[jive.profile(biography).value]</field> <Field name="userprofile_pictureurl">%[thumbnailurl]</field> <Field name="userprofile_work ">%[ s(work).value]</field> <Field name="userprofile_workphone">%[phonenumbers(work).value]</field> <Field name="mobile">%[phonenumbers(mobile).value]</field> <Field name="syslocation">%[location]</field> <Field name="sysfiletype">csuser</field> <!-- Jive system fields --> <Field name="syscsitemtype">user</field> </Fields> </Mapping> <Mapping type="poll"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">cspoll</field> <!-- Jive system fields --> 4www.coveo.com 27

32 <Field name="syscsitemtype">poll</field> </Fields> </Mapping> <Mapping type="post"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csblogpost</field> <!-- Jive system fields --> <Field name="syscsitemtype">blog Post</Field> </Fields> </Mapping> <Mapping type="project"> <Title>%[name]</Title> <Body>%[description]</Body> <Fields> <Field name="sysdtdue">duedate</field> <Field name="sysauthor">%[creator.displayname]</field> <Field name="sysfiletype">csproject</field> <!-- Jive system fields --> <Field name="syscsitemtype">project</field> </Fields> </Mapping> <Mapping type="space"> <Title>%[name]</Title> <Body>%[description]</Body> <Fields> <Field name="sysfiletype">cscommunity</field> <!-- Jive system fields --> <Field name="syscsitemtype">community</field> </Fields> </Mapping> <Mapping type="systemblog"> <Title>%[name]</Title> <Body>%[description]</Body> <Fields> <Field name="sysfiletype">cssystemblog</field> <!-- Jive system fields --> <Field name="syscsitemtype">system Blog</Field> </Fields> </Mapping> <Mapping type="task"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysdtdue">duedate</field> <Field name="sysfiletype">cstask</field> <!-- Jive system fields --> <Field name="syscsitemtype">task</field> <Field name="syscstaskassignedto">%[owner.extra.displayname]</field> </Fields> </Mapping> <Mapping type="update"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csupdate</field> <!-- Jive system fields --> <Field name="syscsitemtype">update</field> </Fields> </Mapping> <Mapping type="video"> <Title>%[subject]</Title> <Body><![CDATA[ <html> %[content.text] </html> ]]></Body> <Fields> <Field name="sysfiletype">csvideo</field> <!-- Jive system fields --> <Field name="syscsitemtype">video</field> 4www.coveo.com 28

33 </Fields> </Mapping> </Mappings> 7.3 Modifying Hidden OpenText Content Server Source Parameters The Add Source and Source:... General pages of the Administration Tool present the parameters with which you can configure the connector for most OpenText Content Server (OTCS) setups. More advanced and more rarely used parameters are hidden. You can choose to make one or more of these parameters appear in the Add Source and Source:... General pages of the Administration Tool so that you can change their default value. Consider changing values of hidden parameters when you encounter issues. The following list describes the advanced hidden parameters available with OTCS sources. The parameter type (integer, string ) appears between parentheses following the parameter name. SpecificContentDeletionNode (String) CES (September 2016) This ID of the node enabled on the OTCS server used for the content deletion process. The parameter value can either be an UndeleteWS or a Recycle Bin node ID. The default value is -1, which tells the connector to ignore the parameter. Notes: When available, you find the Recycle Bin node ID after objid= in the Content Server URL. Example: In the following OpenText Content Server URL, the Recycle Bin node ID is : The parameter is necessary when the connector cannot automatically detect the UndeleteWS node or Recycle Bin ID, which is necessary to take account of deleted items during incremental refreshes. oolean) CES (September 2016) Whether to add anonymous access if "public access" is specified on the content object. The default value is False. UseOtcsContentTypes (Boolean) CES (June 2016) Whether to use the content types returned by OTCS instead of "binary file". The default value is False. Note: When you set the parameter value to True, update the document type set used by your OTCS source to ensure all content types returned by OTCS are indexed. Example: When you want to index all Microsoft Office documents (Word, Excel, and PowerPoint), ensure the following document types are contained in the document set used by the source:.doc,.dot,.docx,.dotx,.docm,.dotm,.xls,.xlt,.xla,.xlsx,.xltx,.xlsm,.xltm,.xlam,.xlsb,.ppt,.pot,.pps,.ppa,.pptx,.potx,.ppsx,.potx,.ppsx,.ppam,.pptm,.potm,.ppsm BatchSize (Integer) Number of items to fetch per request made to the OTCS. The default value is 256. The minimum value is 1. A 4www.coveo.com 29

34 small value forces the connector to make small but frequent queries to OTCS. A larger value leads to larger and less frequent queries. WebServiceConfigFile (String) The path and file name of a custom configuration file. In rare cases where the connector encounters communication issues with Windows Communication Foundation (WCF), you can modify the way in which the connector communicates with OTCS by creating and specifying a custom configuration file (see the Microsoft document Configuring Services Using Configuration Files). ItemTypesToIndex (String) By default, this parameter is empty so that all supported OTCS item types are indexed. You can use this parameter to restrict the types of OTCS items to indexed by entering only the OTCS item types that you want to index, separated by a semi-colon ;. You can easily find the values to enter in this parameter from the Type of items in OpenText Content Server. In the OTCS Workspace, simply hover a discussion item. The tooltip indicates the value to enter in the parameter. SpecificRootNode (Integer) (deprecated) CES (July 2014) Note: CES (August 2014) The Addresses parameter replaces it (see Configuring and Indexing an OpenText Content Server Source). By default, the connector crawls the whole OTCS content from the Enterprise Workspace root. You can use this parameter to specify to start crawling from another root node or from a subnode by entering the node ID. You can find this ID for a node in OTCS by clicking the Functions icon of an item, selecting Properties > General on the menu, clicking Change next to Nickname, and then read the Item ID value. 4www.coveo.com 30

35 Example: When you want to create an OTCS source only for one project, in the project General property tab, read the Item ID value, like 4094 in the following example. Note: Using certain item types as the root node will result in an error when retrieving their permissions. All item types receiving their permissions from their parents (such as Task, News, all types under Discussion, and possibly other types) are not supported as the root node. NumberOfRefreshThreads (Integer) This parameter determines the number of threads used to simultaneously crawl OTCS. The default value is 1. RetrieveFullNodeData (Boolean) By default this parameter is set to True to instruct the connector to perform additional OTCS requests to extract all node metadata and allow to get the OTCS Category data. When you do not want to index OTCS Category data, set this parameter to False to roughly double the crawling speed. OTCSVersion (String) CES (May 2013) This parameter allows to specify the version of the OTCS/Livelink source to crawl. You need to add this parameter only when you want to crawl a Livelink version source. The two possible values are: 10sp2 - The default to crawl an OpenText Content Server source To crawl a Livelink source. RetrieveUsers (Boolean) CES (August 2013) When set to True, this parameter instructs the connector to retrieve the OTCS users. The default value is False. Example: When the authors of OTCS documents are user IDs, not the user names, set the RetrieveUsers parameter to True to retrieve the users. You can then map the user IDs to the user names so that in the search results, you can display user names rather than user IDs. 4www.coveo.com 31

36 To modify hidden OpenText Content Server source parameters 1. Refer to "Adding an Explicit Connector Parameter" on page 32 to add one or more OpenText Content Server hidden source parameters. 2. For a new OpenText Content Server source, access the Add Source page of the Administration Tool to modify the value of the newly added advanced parameter: a. Select Index > Sources and Collections. b. Under Collections, select the collection in which you want to add the source. c. Under Sources, click Add. d. In the Add Source page, edit the newly added advanced parameter value. 3. For an existing OpenText Content Server source, access the Source:... General page of the Administration Tool to modify the value of the newly added advanced parameter: a. Select Index > Sources and Collections. b. Under Collections, select the collection containing the source you want to modify. c. Under Sources, click the existing OpenText Content Server source in which you want to modify the newly added advanced parameter. d. In the Source:... General page, edit the newly added advanced parameter value. 4. Rebuild your OpenText Content Server source to apply the changes to the parameters. 7.4 Adding an Explicit Connector Parameter Connector parameters applying to all sources indexed using this connector are called explicit parameters. When you create or configure a source, the Coveo Enterprise Search (CES) 7.0 Administration Tool presents parameters with which you can configure the connector for most setups. For many connectors, more advanced and more rarely used parameters also exist but are hidden by default. CES then uses the default value associated with each of these hidden parameters. You can however choose to make one or more of these parameters appear in the Add Source and Source:... General pages of the Administration Tool so that you can change their default value. To add an explicit connector parameter 1. On the Coveo server, access the Administration Tool. 2. Select Configuration > Connectors. 3. In the list on the Connectors page, select the connector for which you want to show advanced hidden parameters. 4. In the Parameters section of the selected connector page, click Add Parameter for each hidden parameter that you want to modify. 4www.coveo.com 32

37 Note: The Add Parameter button is present only when hidden parameters are available for the selected connector. 5. In the Modify the parameters of the connector page: a. In the Type list, select the parameter type as specified in the parameter description. b. In the Name box, type the parameter name exactly as it appears in the parameter description. Parameter names are case sensitive. c. In the Default Value box, enter the default value specified in the parameter description. Important: Do not set the value that you want to use for a specific source. The value that you enter here will be used for all sources defined using this connector so it must be set to the recommended default value. You will be able to change the value for each source later, in the Add Source and Source:... General pages of the Administration Tool. d. In the Label box, enter the label that you want to see for this parameter. Example: To easily link the label to the hidden parameter, you can simply use the parameter name, and if applicable, insert spaces between concatenated words. For the BatchSize hidden parameter, enter Batch Size for the label. 4www.coveo.com 33