metaengine DataConnect For SharePoint 2007 Configuration Guide

Transcription

1 metaengine DataConnect For SharePoint 2007 Configuration Guide metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 1

2 Contents Introduction... 5 Installation and deployment... 6 Installation... 6 System Requirements for metaengine DataConnect Designer... 6 Installing metaengine DataConnect Designer... 6 System Requirements for metaengine DataConnect for SharePoint... 7 Deploying metaengine DataConnect for SharePoint... 7 Upgrading an existing metaengine DataConnect installation... 7 Deploying metaengine DataConnect application configurations... 7 Licensing... 9 Overview... 9 Viewing metaengine licenses and status... 9 Requesting a metaengine license... 9 Adding a metaengine license Logging Configuring Trace logging in a DataConnect web site Configuring log4net in a DataConnect web site metaengine DataConnect for SharePoint Fundamentals SharePoint Custom Fields Data Lookup Column Tagging Column Choice Column Filtered Choice Column Default Inheritance SharePoint List and Site Templates DataConnect SharePoint Features metaenginedataconnect metaenginedataconnect.managecfg metaenginedataconnect.vocab SharePoint Custom Timer Jobs metaengine CORE XML Update metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 2

3 metaengine Field Validation Scheduled metaengine Choice Updater SharePoint Custom Administration (stsadm) Commands me-getconfigfile me-setconfigfile me-disablehandlers me-enablehandlers me-licenses me-addlicense me-licenserequest me-restarttimer DataConnect Application Module Providers SharePoint List Data Connection Provider SharePoint History Provider SharePoint Location Provider SharePoint Suggestion Provider SharePoint User Provider Building metaengine DataConnect application configurations Getting Started Enterprise Library DataConnect General Settings Data Connections Data Connection General Xml Data Connection History Providers No History Provider Logging History Provider Location Providers Web Location Provider Suggestion Providers No Suggestion Provider Logging Suggestion Provider User Providers Windows User Provider metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 3

4 Building metaengine DataConnect for SharePoint configurations SharePoint List Data Connection History Providers Location Providers Suggestion Providers User Providers metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 4

5 Introduction metaengine DataConnect is an ASP.Net application for browsing and searching controlled vocabularies. Each vocabulary is sourced from a data connection which can contain XML documents or external data sources using custom providers. Each data connection includes a definition of the Fields and Relationships that the data source contains. Relationships include hierarchies such as Broader and Narrower categories, and associated relationships such as Related Items and Preferred Terms. A Data Service is available for each data connection that provides access to the information in XML or JavaScript (JSON) format. The data services can be queried using specific business properties or relationships and utilised by developers in custom solutions. A configurable Item Selector is provided for each data connection that enables users to pick items by searching the connection or browsing using relationships. An item s detail can be displayed showing an item s description and its relationships to other items. A user can navigate to and select other items by clicking on the relationships links. metaengine DataConnect is typically used within Web Content Management and Document Management Systems to label web pages and documents. metaengine DataConnect for SharePoint integrates the full capability of DataConnect into any Windows SharePoint Services v3 or Microsoft Office SharePoint Server 2007 List or Document Library. Two new column types Data Column and Tagging Column are provided that enable users to pick data values from connections using Item Selector or Auto Suggestion features. metaengine DataConnect for SharePoint also includes DataConnect application module providers that utilise SharePoint storage and functionality. Providers are supplied for Data Connection, History, Suggestion, Location and User functionality. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 5

6 Installation and deployment In this section installation refers to the process of installing metaengine DataConnect Designer onto a development workstation and deployment refers to the process of installing the metaengine DataConnect Runtime and application configuration files onto a test or production SharePoint server. Development Workstation metaengine DataConnect Designer with SharePoint2007 extensions Deploy Application Configuration files Test/Production SharePoint Server SharePoint Layouts metaengine configuration metaengine DataConnect SharePoint Solution ASP.Net AJAX Extensions or MS.Net 3.5 Framework.Net Framework 2.0.Net Framework 2.0 Installation System Requirements for metaengine DataConnect Designer Windows XP Professional or Windows Server 2003 Microsoft.Net Framework 2.0 metaengine DataConnect uses Microsoft ASP.NET AJAX. It provides user interface components known as ASP.Net AJAX behaviours that use Microsoft ASP.NET AJAX capabilities. It is a prerequisite to have either the Microsoft ASP.Net AJAX Extensions 2.0 or Microsoft.Net Framework version 3.5 installed on the Production SharePoint server. Separate installs of metaengine DataConnect are available that target either the Microsoft ASP.Net AJAX Extensions 2.0 or Microsoft.Net Framework version 3.5. More information on Installing ASP.NET AJAX can be found at and more general documentation at Installing metaengine DataConnect Designer To install metaengine DataConnect Designer open the file metaenginedesigner.zip and extract the contents to a folder e.g. c:\pemberton\metaenginedesigner. The following files should be in the folder: 1. Interop.MSDASC.dll metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 6

7 2. metaengineconfiguration.exe 3. metaengineconfiguration.exe.manifest 4. Microsoft.Practices.EnterpriseLibrary.Common.dll 5. Microsoft.Practices.EnterpriseLibrary.Configuration.dll 6. Microsoft.Practices.EnterpriseLibrary.Configuration.Design.dll 7. Microsoft.Practices.EnterpriseLibrary.Logging.dll 8. Pemberton.metaEngine.DataConnect.dll 9. Pemberton.metaEngine.DataConnect.Configuration.Design.dll 10. Pemberton.metaEngine.DataConnect.Xml.dll 11. Pemberton.metaEngine.DataConnect.Xml.Design.dll 12. Pemberton.metaEngine.DataConnect.SharePoint2007.dll 13. Pemberton.metaEngine.DataConnect.SharePoint2007.Design.dll System Requirements for metaengine DataConnect for SharePoint It is a prerequisite to have the Microsoft ASP.Net AJAX Extensions 2.0 installed on the SharePoint server. Deploying metaengine DataConnect for SharePoint To install DataConnect for SharePoint open the file metaenginedataconnectsharepoint.zip and extract the contents to c:\temp. The following files should be present: 1. InstallDataConnect.bat 2. SharePointDataConnect.wsp To install open a command prompt and type: InstallDataConnect.bat " Where is the URL of an existing SharePoint web application. The install script adds the DataConnect solution file to the SharePoint farm and activates the DataConnect SharePoint Web Application feature on the target web application. To activate the feature on other existing web applications use either SharePoint Central Administration > Application Management > Manage Web Application Features or stsadm: stsadm -o activatefeature -name "metaenginedataconnect" -url Note: the feature will be activated by default on new web applications created after installation. Upgrading an existing metaengine DataConnect installation To upgrade an existing DataConnect installation with a new solution file (wsp) run the following command ensuring that the filename parameter points to the location of the updated solution file. stsadm -o upgradesolution -name SharePointDataConnect.wsp -filename SharePointDataConnect.wsp allowgacdeployment immediate Deploying metaengine DataConnect application configurations To install a metaengine DataConnect application configuration: metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 7

8 Produce an application configuration (see metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 8

9 Building metaengine DataConnect application configurations Getting Started To create a new metaengine DataConnect application configuration: Open metaengineconfiguration.exe from the installed location. Click File > New Application To save an application: Click File > Save Application Select a folder for the configuration files Type metaengine.config into the file name box Click Save To open an existing application: Click File > Open Application Select a folder with existing configuration files Select the metaengine.config file Click Open Enterprise Library Microsoft Patterns and Practices Enterprise Library is a set of application blocks designed to assist developers with common enterprise development challenges. DataConnect uses modified versions of the Enterprise Library June 2005 Configuration block. The Configuration application block settings metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 9

10 displayed in the Designer do not need to be edited. These settings describe how the configuration will be saved. DataConnect General Settings The metaengine DataConnect settings node contains the default application module providers. Default application module providers are chosen from the available list of providers and are used when a specific provider has not been specified. DefaultHistoryProvider DefaultLocationProvider DefaultSuggestionProvider DefaultUserProvider Used by data connections that have history services turned on and have no history provider specified. Used by data connections when no location provider rule set matches the current resource url. Used by data connections that have suggestion services turned on and have no suggestion provider specified. Always used across all data connections to retrieve information on the current user. Data Connections The Data Connections node contains all the configured connections. To create a new Data Connection right click on the Data Connections node and select New > Provider. Available data connection providers will be dependent on your installation environment. Data Connection General The settings in the section below are common to all data connection providers. General Name ShortDescription Title The name of the data connection. This is used as the URL path to the data connection. The name should only contain alphanumeric characters. For example if the name is IPSV the data connection schema will be available at [server/virtual_dir are dependent on your environment and dataconnect is the out of the box path used by the DataConnect httphandler] The description of the data connection. This will be used in browse and selection user interfaces to provide the user information about the data connection. The title of the data connection. This will be used in browse and selection user interfaces to provide the user information about the data connection. General Data Connection Settings Feedback Template The value of this field will be used in the generated by users clicking on the Feedback link in browse and selection user interfaces. ItemTitle The name given to a data item in the browse and selection user interfaces. For example ItemTitle may be Keyword. Owner OwnerName The value of this field will be used as the address generated by users clicking on the Feedback link in browse and selection user interfaces. The value of this field will be used as the name when users click metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 10

11 PluarlisedItemTitle RowLimit Provider Settings HistoryProviderEnabled HistoryProviderType MaximumHistoryItems MaximumSuggestions SuggestionsProviderEnabled SuggestionsProviderType on the Feedback link in browse and selection user interfaces. The name given to more than one data item in the browse and selection user interfaces. For example PluarlisedItemTitle may be Keywords. The number of data items that the data service provides in any single call to the either the GetItems method of the data web service or the getitems.aspx data page. [Result paging is not supported in the current release but will be added in future releases.] The browse and selector controls use these data services to fetch items so this number controls the number of items that will be rendered in a single search. Setting row limit above 1000 may impact the performance of the client side control rendering. Determines whether a history provider is used by the data connection to retrieve and record a user s previously used items. The History provider the data connection should use. The maximum number of a user s previously used items that should be returned in data requests (and presented to the user). The maximum number of suggested items that should be returned in data requests (and presented to the user). Determines whether a suggestions provider is used by the data connection to retrieve suggested items for the item selector user interface. The Suggestions provider the data connection should use. Each Data Connection will have a set of Fields and Relationship Types. The type of data connection you are configuring will determine whether the Fields and Relationship Types are generated and editable in the Configuration window or whether the provider itself will generate them dynamically at runtime. Fields Fields are used by the data connection to determine what properties of a data item a data service returns and how those properties are used by DataConnect user interfaces. The type of data connection provider will determine if fields are editable and if you can create or remove fields. Note [The provider may not display fields in the designer if they are automatically generated at runtime.]. Each field maps onto a data entry/attribute/column in the underlying data source and has a small number of properties that determines how the field behaves in the browse and selector user interfaces (for example whether it is displayed in the detail pane). Name ColumnName DisplayName Filterable Hidden The name of the field. The name should only contain alphanumeric characters. Identifies the data entry/attribute/column in the underlying data source the field maps to. The display name of the field used in browse and selector user interfaces. Determines whether the field can be used as a query filter in data service calls. The Title field must be filterable. Determines whether the field value is displayed in the detail pane of browse and selector user interfaces. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 11

12 Every data connection provider must always have an ID and Title field. A field named PreferredItem (if available) is used to by the selector interface to replace the display title of a selected item with an alternative at the time of selection. Relationship Types Relationship Types are used by a data connection to link data items. Relationship types and related items are used in the browse and selector user interfaces to enable a user to navigate between data items. Hierarchical relationships are displayed in the tree view of browse and selector user interfaces. When a data item is explicitly retrieved by its ID (e.g. getitembyid.aspx) any related items for each relationship type are returned. The type of data connection provider will determine if relationship types are editable and if you can create or remove relationship types. Name Description DisplayName Directional FromLabel IsHierarchy RelationshipKey ToLabel The name of the relationship type. The name should only contain alphanumeric characters. The name is used to specify the relationship in data service calls to GetChildItems and GetTopLevelItems. A description of the relationship type. The display name of the relationship type used in the tree view of the browse and selector user interfaces. Specifies whether the relationship is directional. This can be used by data connection providers to determine how to query for related items. It is also used by the browse and selector user interfaces to determine the display of related items displays labels. This is always true for hierarchical relationships. The heading label used for items from a data item to related items. For example in a parent-child relationship the FromLabel may be Parent Item or Broader. Specifies whether the relationship type is a hierarchy. This is used by the browse and selector user interfaces to determine if the relationship should be displayed in the tree view. The linking or foreign key used to retrieve related items. This is chosen from the available fields in the data connection. Typically a data connection provider will retrieve items where the column specified in the RelationshipKey field equals the column specified in the Id field. The heading label used for items from related items to a data item. For example in a parent-child relationship the ToLabel may be Child Item or Narrower. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 12

13 Xml Data Connection To create a new XML Data Connection right click on the Data Connections node and select New > XML Data Connection. Fill in the core data connection provider properties. An xml data connection sources data from an xml file. The file can be specified by URL, absolute file path or a file path relative to the web application directory. Data items are retrieved and filtered from the data source using XPath queries. The XML data connection must be configured with a valid XPathToItem that identifies the path to a data item. In the simple xml file below the XPathToItem would be Departments/Department. <?xml version="1.0" encoding="utf-8"?> <Departments> <Department> <DeptID>123</DeptID><DeptName>Department 123</DeptName> </Department> <Department> <DeptID>124</DeptID><DeptName>Department 124</DeptName><ParentDept>123</ParentDept> </Department> </Departments> [Note the xml data connection does not currently support the use of namespaces. Additionally only elements and attributes that are direct child of the data item can be used as Fields. It is recommended that a XSL transform file is used to remove namespace declarations. Use of namespaces in the source xml file will mean no results are returned.] To specify a new xml data connection: 1. Choose an xml data file using the file selector. 2. If the xml file uses no namespaces, with all required information contained in child elements and child attributes of the data item click yes to the question below. *Note: Clicking Yes will delete current Fields and Relationship Types and generate new ones] If the xml data file requires a transformation file click no. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 13

14 3. If the xml data requires transformation choose an XslTransformFile using the file selector. 4. Click yes to the dialog to generate a new schema. 5. Click the button in the XPathToItem field to open the XPath selector dialog to choose an element for the data item. Highlight the required element and select OK. 6. Selecting an element will generate new Field nodes for each possible child element and attribute of the data item element. 7. Edit the fields as required. Every data connection provider must always have an ID and Title field. 8. Remove fields that will not be used in the detail view or in relationships. 9. Create Relationship Types as required. 10. If required change the xml data and/or xml transformation file location to be a URL or a filename relative to the configuration directory. Xml Data Connection Settings MinutesToCache XmlDataFile XPathToItem The duration that the xml data file and transform file should be cached for. The path to the xml data file. The file can be specified by URL, absolute file path or a file path relative to the web application directory. The XPath that identifies a data item with the file. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 14

15 XslTranformFile The path to the xml transform (XSL) file used to transform the xml data file before data queries are performed. The file can be specified by URL, absolute file path or a file path relative to the web application directory. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 15

16 History Providers A history provider is responsible for saving and retrieving items that a user selects from a data connection. To create a new History Provider right click on the History Providers node and select New > Provider. Available history providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration and a specific provider on a data connection. No History Provider The No History provider takes no action with history requests and can be used to disable history functionality. Logging History Provider The Logging History provider logs all history requests and enables application tracing. Location Providers A location provider is responsible for retrieving information about, and the content of, a resource being labelled using Item Selector dialog and extender controls. To create a new Location Provider right click on the Location Providers node and select New > Provider. Available location providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration. Url Filters control which location provider is used to provide information and content for which url resource. If the match filters do not return a location provider then the default location provider is used. To add a new Url filter to a location provider right click on the Url Filters node within the location provider selector and select New > condition type. The conditions available will be determined by the DataConnect extensions currently installed. The core Url filters available are: And Not Or Page Url Enables a logical And to be performed on a set of rules. To add rules right click on the And node and click New. The And rule returns true if all the rules within the condition return true. Enables a logical Not to be performed on a rule. To add a rule, right click on the Not node and click New. The Not rule returns true if the rule within the condition returns false. Enables a logical Or to be performed on a set of rules. To add rules right click on the Or node and click New. The Or rule returns true if all one or more rules within the condition return true. Enables selection of specific pages within a web application based on the page url. At runtime the filter rule executes a comparison using the supplied MatchText against the context url provided. Available match types are Regular Expression (RegExp), Starts With, Ends With, Contains and Exact. For more information on Regular Expressions visit metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 16

17 For example to select all product.aspx pages set the MatchTest to product.aspx and the MatchType to Contains. Web Location Provider The web location provider returns the content available at the context url. Suggestion Providers A suggestion provider is responsible for suggesting items to label a specific resource. To create a new Suggestion Provider right click on the Suggestion Providers node and select New > Provider. Available suggestion providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration and a specific provider on a data connection. No Suggestion Provider The No Suggestion provider takes no action with suggestion requests and can be used to disable suggestion functionality. Logging Suggestion Provider The Logging Suggestion provider logs all suggestion requests and enables application tracing. It attempts to save the content of a resource passed to the suggestion provider into c:\window\temp. This can be used to validate the operation of the current Location Provider to retrieve content. User Providers A user provider is responsible for retrieving information about a user labelling a resource using Item Selector dialog and extender controls. To create a new User Provider right click on the User Providers node and select New > Provider. Available user providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration. Windows User Provider The Windows User provider returns the current ASP.Net Authenticated user if available and if not returns the current windows user. 1. Building metaengine DataConnect for SharePoint configurations) metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 17

18 2. Copy the application configuration files to a new folder within the SharePoint Layouts metaengine folder: C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\TEMPLATE\LAYOUTS\metaEngine 3. For example: C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\TEMPLATE\LAYOUTS\metaEngine\newCfg This folder should include the following files: a. metaengine.config b. selectorconfiguration.config 4. To activate the configuration on a web application use either SharePoint Central Administration > Operations > Manage metaengine Configuration or stsadm: stsadm -o me-setconfigfile -url " -configfile "C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\TEMPLATE\LAYOUTS\metaEngine\samples\metaEngine.config" metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 18

19 Licensing Overview Each SharePoint front end web server running metaengine requires a valid metaengine license. After installing metaengine a 30 day trial license is automatically activated. When the trial period expires some metaengine functionality will be disabled. To license metaengine, purchase metaengine licenses as required at After purchasing and software installation each server can be licensed by requesting a license and then applying the license on the server. License requests are made via to license@metaengine.com. License requests and applications can be performed from either SharePoint Central Administration or stsadm. Install metaengine Request License Receive License Apply License Viewing metaengine licenses and status Via Central Administration 1. Open SharePoint Central Administration 2. Click on Application Management 3. From the External Service Connections group, click Manage metaengine DataConnect 4. Click Manage metaengine Licenses Via stsadm 1. Open a new command prompt 2. Navigate to the SharePoint bin directory e.g. cd C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\BIN 3. Type stsadm -o me-licenses Requesting a metaengine license Via Central Administration 1. Open SharePoint Central Administration 2. Click on Application Management 3. From the External Service Connections group, click Manage metaengine DataConnect 4. Click Manage metaengine Licenses 5. To immediately create an request click Request License via and then click send OR 6. Save a request file to send later click Save License Request File 7. Send an to license@metaengine.com with the request file attached. Via stsadm 1. Log onto the web application server 2. Open a new command prompt metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 19

20 3. Navigate to the SharePoint bin directory e.g. cd C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\BIN 4. Type stsadm -o me-licenserequest -path c:\licreq (the optional path parameter specifies the location the request file will be saved into) 5. Send an to with the request file attached. Adding a metaengine license Via Central Administration 1. Open SharePoint Central Administration 2. Click on Application Management 3. From the External Service Connections group, click Manage metaengine DataConnect 4. Click Manage metaengine Licenses 5. Click Add License next to the server to be licensed 6. Click Browse and select the license file received from license@metaengine.com 7. Click Upload Via stsadm 1. Log onto the web application server to be licensed 2. Open a new command prompt 3. Navigate to the SharePoint bin directory e.g. cd C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\BIN 4. Type stsadm -o me-addlicense -keyfile c:\license.txt(where the keyfile parameter specifies the location of the license file received from license@metaengine.com) Logging DataConnect logs information and exceptions using either Microsoft.Net System.Diagnostics.Trace logging or log4net logging. Configuring Trace logging in a DataConnect web site Enable Tracing To enable tracing, locate the web.config for your SharePoint web application (e.g., C:\inetpub\wwwroot\wss\VirtualDirectories\8081) and edit the web.config file by adding the following within the root <configuration> node. A good place to put this snippet is just above the last line in the file that has </configuration>; however, you'll want to make sure there is not already a <system.diagnostics> node first. web.config snippet: <system.diagnostics> <switches> <!-- 0=none, 1-errors, 2=warnings, 3=info, 4=verbose --> <add name="metaengine.dataconnect.trace" value="4" /> </switches> </system.diagnostics> You will likely need to perform an IISRESET after making this change. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 20

21 View Trace The easiest way to view the trace is to download DebugView on your web server. When using, make sure you go to the Capture menu and choose Capture Win32. After you have updated your web.config, performed an IISRESET and started DebugView, you can navigate to pages within the web site and you will see trace messages related to DataConnect. Configuring log4net in a DataConnect web site Scenario1 log4net is not already used in your SharePoint web application Add log4net.dll into the GAC or the web application _app_bin folder Add new element into <httpmodules> in the SharePoint web application web.config <add name="log4netconfiginit" type="pemberton.metaengine.dataconnect.log4netconfiginit, Pemberton.metaEngine.DataConnect, Version= , Culture=neutral, PublicKeyToken=ab6be135e38f5e9d" /> Add new element into the <appsettings> element in the web.config. this should point to the location of a valid log4net configuration file. <add key="metaengine.log4netconfigfile" value="log4net.config"/> An example log4net configuration file is shown below: <?xml version="1.0" encoding="utf-8"?> <log4net> <appender name="rollingfileappender" type="log4net.appender.rollingfileappender"> <file value="logs\\log-file.txt" /> <appendtofile value="true" /> <rollingstyle value="composite" /> <maxsizerollbackups value="14" /> <maximumfilesize value="15000kb" /> <datepattern value="yyyymmdd" /> <staticlogfilename value="true" /> <layout type="log4net.layout.patternlayout"> <conversionpattern value="{%level}%date{mm/dd HH:mm:ss}- %message%newline"/> </layout> </appender> <root> <level value="all" /> <appender-ref ref="rollingfileappender"/> </root> </log4net> Check the web application users have the permission to write to the logs location. Scenario2 log4net is already used in the SharePoint web application Include metaengine.dataconnect in the list of loggers in the log4net configuration file. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 21

22 metaengine DataConnect for SharePoint Fundamentals metaengine DataConnect for SharePoint integrates the full capability of DataConnect into any Windows SharePoint Services v3 or Microsoft Office SharePoint Server 2007 List or Document Library. Two new column types Data Column and Tagging Column are provided that enable users to pick data values from connections using Item Selector or Auto Suggestion features. metaengine DataConnect for SharePoint also includes DataConnect application module providers that utilise SharePoint storage and functionality. Providers are supplied for Data Connection, History, Suggestion, Location and User functionality. SharePoint Custom Fields The metaengine field types provide the ability to add data lookup, choice, filtered choice and tagging columns across the SharePoint Farm once the DataConnect solution has been deployed. To create and use DataConnect columns on a web application the DataConnect web application feature must be activated. DataConnect data lookup, choice and tagging columns use a secondary related column to store information and column settings for query usage and for use in Office client interfaces. The secondary column is automatically provisioned for columns created via the user interface and feature definitions. For columns created from feature definitions (e.g. Site Columns) the secondary related columns can be provisioned using the feature. DataConnect filtered choice columns do not use a secondary related column. Each DataConnect custom field type can also store keyword path information in an additional hierarchy path column. For example if the taxonomy keyword Football is selected in the column, the hierarchy path column may store Leisure/ Sports/ Football. For more information about provisioning columns see the metaengine DataConnect SharePoint Developers Guide. Data Lookup Column The out-of-the-box SharePoint List does not provide capabilities to read directly from external data sources such as Taxonomies, Thesauri or Controlled Vocabularies but by introducing the metaengine Data Column users can accurately label SharePoint items and documents. The lookup column enables users to label items and documents in a team site, and in Microsoft Office 2003 and Within Office users are presented with a quick choice of previously assigned labels and relevant choices highlighted by Team Site administrators. The data lookup column constrains user entry to values from the data connection. The Data Column can be used to filter items in SharePoint views and increase relevancy in search results. The Data Column can be included in Lists, Document Libraries, Content Types, Site Directories, SharePoint features and deployed as part of SharePoint site and list schemas. For more information about creating Data Lookup Columns as a team site administrator using the SharePoint user interface see the metaengine DataConnect User Guide for SharePoint metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 22

23 For more information about using SharePoint Features to include Data Lookup Columns in Site Columns, Content Types, Lists and Libraries see the metaengine DataConnect SharePoint Developers Guide. Tagging Column The Tagging Column enables users to label items and documents in a team site, and in Microsoft Office 2003 and 2007 using a Web 2.0 style tagging user interface. This includes auto suggestion of labels from a Data Connection and quick addition of labels from highlighted choices and previously used labels. The tagging column does not constrain user entry to values from the data connection. The column can be edited in Office using the standard free form interface. The Tagging Column can be used to filter items in SharePoint views. The Tagging Column can be included in Lists, Document Libraries, Content Types, Site Directories, SharePoint features and deployed as part of SharePoint site and list schemas. For more information about creating Tagging Columns as a team site administrator using the SharePoint user interface see the metaengine DataConnect User Guide for SharePoint For more information about using SharePoint Features to include Tagging Columns in Site Columns, Content Types, Lists and Libraries see the metaengine DataConnect SharePoint Developers Guide. Choice Column The Choice Column enables users to label items and documents in a team site, and in Microsoft Office 2003 and 2007 using choices sourced from an external or central data connection. The column displays in exactly the same manner as the regular SharePoint Choice or MultiChoice column. The choices are updated from a data connection by a custom SharePoint Timer job Scheduled metaengine Choice Updater. The frequency of the schedule can be managed per web application via SharePoint Central Administration Manage metaengine Configuration. The Choice Column can be used to filter items in SharePoint views. The Choice Column can be included in Lists, Document Libraries, Content Types, Site Directories, SharePoint features and deployed as part of SharePoint site and list schemas. For more information about creating Choice Columns as a team site administrator using the SharePoint user interface see the metaengine DataConnect User Guide for SharePoint For more information about using SharePoint Features to include Choice Columns in Site Columns, Content Types, Lists and Libraries see the metaengine DataConnect SharePoint Developers Guide. Filtered Choice Column The Filtered Choice Column enables users to label items and documents in a team site, using choices sourced from an external or central data connection. Choices displayed to the user are dependent upon the value in a linked parent column. For example the parent column might contain Countries and the filtered choice column would show Cities from the currently selected Country. The column displays as dropdown in the browser. The Filtered Choice Column can be used to filter items in SharePoint views. The Filtered Choice Column can be included in Lists, Document Libraries, Content Types, Site Directories, SharePoint metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 23

24 features and deployed as part of SharePoint site and list schemas. The Filtered Choice Column cannot be edited in Office 2003, 2007 clients or the datasheet interface. For more information about creating Filtered Choice Columns as a team site administrator using the SharePoint user interface see the metaengine DataConnect User Guide for SharePoint For more information about using SharePoint Features to include Filtered Choice Columns in Site Columns, Content Types, Lists and Libraries see the metaengine DataConnect SharePoint Developers Guide. Default Inheritance DataConnect Data Lookup, Choice, Filtered Choice and Tagging Columns created from Site Columns installed via a feature can inherit default and highlight choices from a column with the same name on another list within the site or from a column with the same name on the connected Site Directory list. For more information about default inheritance in metaengine columns see the metaengine DataConnect SharePoint Developers Guide. SharePoint List and Site Templates SharePoint Lists and Libraries that contain provisioned metaengine DataConnect fields can be saved as SharePoint Templates (stp) files to enable reuse. The template will save the metaengine column properties. For the template to work on another server metaengine DataConnect must be installed and the data connection services referenced in the column must be available. DataConnect SharePoint Features Deploying the DataConnect SharePoint solution adds three SharePoint features: metaenginedataconnect, metaenginedataconnect.managecfg and metaenginedataconnect.vocab. metaenginedataconnect metaenginedataconnect is a web application scoped feature primarily responsible for adding entries into the web application configuration (web.config). This feature must be activated on all web applications where DataConnect columns are used. Note: Deactivating this feature on a web application will cause all metaengine columns to be deleted. This includes all tagging data in those columns. metaenginedataconnect.managecfg metaenginedataconnect.managecfg is a farm scoped feature enabling an administrator to change the DataConnect configuration for the web application. The DataConnect configuration controls which data connections are available for use by the columns. metaenginedataconnect.vocab metaenginedataconnect.vocab is a web scoped feature that provides a vocabulary list template. SharePoint Custom Timer Jobs metaengine DataConnect adds 3 timer jobs to each web application: metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 24

25 metaengine CORE XML Update This timer job maintains core metaengine xml files on each server. This job should not be disabled. metaengine Field Validation This timer job maintains information required to optimise the performance of metaengine browse and query interfaces. This job should not be disabled. The job should run daily as a minimum. This job should be run immediately after large content reorganisations and/or migrations. The frequency of the schedule can be controlled per web application via the SharePoint Central Administration Manage metaengine Configuration page. Scheduled metaengine Choice Updater This timer job maintains choice lists used in metaengine Choice columns. This job can be scheduled to run as required via the SharePoint Central Administration Manage metaengine Configuration page. If data connections are very dynamic then the job should run frequently (hourly) however if data connections are largely static the job can run daily. SharePoint Custom Administration (stsadm) Commands metaengine DataConnect adds two custom stsadm commands to enable management of the DataConnect configuration for a web application. me-getconfigfile This command retrieves the current path of the DataConnect configuration file and reports any potential inconsistencies between physical entries in the web.config file and modifications stored inside the SharePoint configuration database. stsadm -o me-getconfigfile -url " me-setconfigfile This command sets the path of the DataConnect configuration file for a web application. stsadm -o me-setconfigfile -url " -configfile "C:\Program Files\Common Files\microsoft shared\web Server Extensions\12\TEMPLATE\LAYOUTS\metaEngine\samples\metaEngine.config" me-disablehandlers This command disables event handlers used by metaengine to track tagging behaviour. This should be used to disable handlers before migration scripts are used to import large volumes of content. The scope parameter can be one of Farm, WebApplication, Site or Web stsadm -o me-disablehandlers -url " -scope WebApplication me-enablehandlers This command enables event handlers used by metaengine to track tagging behaviour. This should be used after migration to enable handlers. stsadm -o me-enablehandlers -url " -scope WebApplication me-licenses This command displays the current status of metaengine licenses on the SharePoint Farm. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 25

26 stsadm -o me-licenses me-addlicense This command adds a metaengine license file to the server. stsadm -o me-addlicense -keyfile "c:\license.txt" me-licenserequest This command generates a metaengine licenses request file in the directory specified in the path parameter. stsadm -o me-licenserequest -path "c:\" me-restarttimer This command restarts the Windows SharePoint Services Timer. If the local parameter is specified only the service on the on the local server is restarted, if the parameter is not specified an attempt is made to restart the timer service on every SharePoint server in the farm. stsadm -o me-restarttimer -local metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 26

27 DataConnect Application Module Providers Some capability supplied by DataConnect and DataConnect data connections can be controlled by configuring DataConnect application module providers. This provides flexibility and extensibility to the core application. metaengine DataConnect for SharePoint extends DataConnect by adding the following providers. SharePoint List Data Connection Provider A data connection provider is responsible for querying and retrieving data items from a data source. The SharePoint list data connection provider uses a SharePoint list or a library as its data source. Data Connections can be configured by specifying the name of the list and the URL of the SharePoint team site that contains the list. After DataConnect for SharePoint installation all lists automatically expose DataConnect data services. This enables users to choose them as column data sources without requiring a service provider to update the server configuration. For more information about using a SharePoint lists data service in a column see the metaengine DataConnect SharePoint Users Guide. SharePoint History Provider A history provider is responsible for saving and retrieving items that a user selects from a data connection. The SharePoint history provider stores all the data items assigned to a list item or document that a user has modified. The SharePoint history provider is scoped to a site collection. The history provider retrieves a users recently used data items within the site collection for use in data column user interfaces. The SharePoint history provider should be used as the default history provider in SharePoint environments. SharePoint Location Provider A location provider is responsible for retrieving information about, and the content of, a resource being labelled using Item Selector dialog and extender controls. The SharePoint location provider retrieves list or document content for use by a suggestion provider. The SharePoint location provider should be used as the default location provider in SharePoint environments. SharePoint Suggestion Provider A suggestion provider is responsible for suggesting items to label a specific resource. The SharePoint suggestion service uses data items stored by the history provider to suggest items to a user based on the location of a resource. It does not provide auto categorisation services. The SharePoint suggestion provider can be used as the default suggestion provider in SharePoint environments. SharePoint User Provider A user provider is responsible for retrieving information about a user labelling a resource using Item Selector dialog and extender controls. The SharePoint user provider retrieves user information from SharePoint. The SharePoint user provider should be used as the default user provider in SharePoint environments. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 27

28 metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 28

29 Building metaengine DataConnect application configurations Getting Started To create a new metaengine DataConnect application configuration: Open metaengineconfiguration.exe from the installed location. Click File > New Application To save an application: Click File > Save Application Select a folder for the configuration files Type metaengine.config into the file name box Click Save To open an existing application: Click File > Open Application Select a folder with existing configuration files Select the metaengine.config file Click Open Enterprise Library Microsoft Patterns and Practices Enterprise Library is a set of application blocks designed to assist developers with common enterprise development challenges. DataConnect uses modified versions of the Enterprise Library June 2005 Configuration block. The Configuration application block settings metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 29

30 displayed in the Designer do not need to be edited. These settings describe how the configuration will be saved. DataConnect General Settings The metaengine DataConnect settings node contains the default application module providers. Default application module providers are chosen from the available list of providers and are used when a specific provider has not been specified. DefaultHistoryProvider DefaultLocationProvider DefaultSuggestionProvider DefaultUserProvider Used by data connections that have history services turned on and have no history provider specified. Used by data connections when no location provider rule set matches the current resource url. Used by data connections that have suggestion services turned on and have no suggestion provider specified. Always used across all data connections to retrieve information on the current user. Data Connections The Data Connections node contains all the configured connections. To create a new Data Connection right click on the Data Connections node and select New > Provider. Available data connection providers will be dependent on your installation environment. Data Connection General The settings in the section below are common to all data connection providers. General Name ShortDescription Title The name of the data connection. This is used as the URL path to the data connection. The name should only contain alphanumeric characters. For example if the name is IPSV the data connection schema will be available at [server/virtual_dir are dependent on your environment and dataconnect is the out of the box path used by the DataConnect httphandler] The description of the data connection. This will be used in browse and selection user interfaces to provide the user information about the data connection. The title of the data connection. This will be used in browse and selection user interfaces to provide the user information about the data connection. General Data Connection Settings Feedback Template The value of this field will be used in the generated by users clicking on the Feedback link in browse and selection user interfaces. ItemTitle The name given to a data item in the browse and selection user interfaces. For example ItemTitle may be Keyword. Owner OwnerName The value of this field will be used as the address generated by users clicking on the Feedback link in browse and selection user interfaces. The value of this field will be used as the name when users click metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 30

31 PluarlisedItemTitle RowLimit Provider Settings HistoryProviderEnabled HistoryProviderType MaximumHistoryItems MaximumSuggestions SuggestionsProviderEnabled SuggestionsProviderType on the Feedback link in browse and selection user interfaces. The name given to more than one data item in the browse and selection user interfaces. For example PluarlisedItemTitle may be Keywords. The number of data items that the data service provides in any single call to the either the GetItems method of the data web service or the getitems.aspx data page. [Result paging is not supported in the current release but will be added in future releases.] The browse and selector controls use these data services to fetch items so this number controls the number of items that will be rendered in a single search. Setting row limit above 1000 may impact the performance of the client side control rendering. Determines whether a history provider is used by the data connection to retrieve and record a user s previously used items. The History provider the data connection should use. The maximum number of a user s previously used items that should be returned in data requests (and presented to the user). The maximum number of suggested items that should be returned in data requests (and presented to the user). Determines whether a suggestions provider is used by the data connection to retrieve suggested items for the item selector user interface. The Suggestions provider the data connection should use. Each Data Connection will have a set of Fields and Relationship Types. The type of data connection you are configuring will determine whether the Fields and Relationship Types are generated and editable in the Configuration window or whether the provider itself will generate them dynamically at runtime. Fields Fields are used by the data connection to determine what properties of a data item a data service returns and how those properties are used by DataConnect user interfaces. The type of data connection provider will determine if fields are editable and if you can create or remove fields. Note [The provider may not display fields in the designer if they are automatically generated at runtime.]. Each field maps onto a data entry/attribute/column in the underlying data source and has a small number of properties that determines how the field behaves in the browse and selector user interfaces (for example whether it is displayed in the detail pane). Name ColumnName DisplayName Filterable Hidden The name of the field. The name should only contain alphanumeric characters. Identifies the data entry/attribute/column in the underlying data source the field maps to. The display name of the field used in browse and selector user interfaces. Determines whether the field can be used as a query filter in data service calls. The Title field must be filterable. Determines whether the field value is displayed in the detail pane of browse and selector user interfaces. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 31

32 Every data connection provider must always have an ID and Title field. A field named PreferredItem (if available) is used to by the selector interface to replace the display title of a selected item with an alternative at the time of selection. Relationship Types Relationship Types are used by a data connection to link data items. Relationship types and related items are used in the browse and selector user interfaces to enable a user to navigate between data items. Hierarchical relationships are displayed in the tree view of browse and selector user interfaces. When a data item is explicitly retrieved by its ID (e.g. getitembyid.aspx) any related items for each relationship type are returned. The type of data connection provider will determine if relationship types are editable and if you can create or remove relationship types. Name Description DisplayName Directional FromLabel IsHierarchy RelationshipKey ToLabel The name of the relationship type. The name should only contain alphanumeric characters. The name is used to specify the relationship in data service calls to GetChildItems and GetTopLevelItems. A description of the relationship type. The display name of the relationship type used in the tree view of the browse and selector user interfaces. Specifies whether the relationship is directional. This can be used by data connection providers to determine how to query for related items. It is also used by the browse and selector user interfaces to determine the display of related items displays labels. This is always true for hierarchical relationships. The heading label used for items from a data item to related items. For example in a parent-child relationship the FromLabel may be Parent Item or Broader. Specifies whether the relationship type is a hierarchy. This is used by the browse and selector user interfaces to determine if the relationship should be displayed in the tree view. The linking or foreign key used to retrieve related items. This is chosen from the available fields in the data connection. Typically a data connection provider will retrieve items where the column specified in the RelationshipKey field equals the column specified in the Id field. The heading label used for items from related items to a data item. For example in a parent-child relationship the ToLabel may be Child Item or Narrower. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 32

33 Xml Data Connection To create a new XML Data Connection right click on the Data Connections node and select New > XML Data Connection. Fill in the core data connection provider properties. An xml data connection sources data from an xml file. The file can be specified by URL, absolute file path or a file path relative to the web application directory. Data items are retrieved and filtered from the data source using XPath queries. The XML data connection must be configured with a valid XPathToItem that identifies the path to a data item. In the simple xml file below the XPathToItem would be Departments/Department. <?xml version="1.0" encoding="utf-8"?> <Departments> <Department> <DeptID>123</DeptID><DeptName>Department 123</DeptName> </Department> <Department> <DeptID>124</DeptID><DeptName>Department 124</DeptName><ParentDept>123</ParentDept> </Department> </Departments> [Note the xml data connection does not currently support the use of namespaces. Additionally only elements and attributes that are direct child of the data item can be used as Fields. It is recommended that a XSL transform file is used to remove namespace declarations. Use of namespaces in the source xml file will mean no results are returned.] To specify a new xml data connection: 11. Choose an xml data file using the file selector. 12. If the xml file uses no namespaces, with all required information contained in child elements and child attributes of the data item click yes to the question below. *Note: Clicking Yes will delete current Fields and Relationship Types and generate new ones] If the xml data file requires a transformation file click no. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 33

34 13. If the xml data requires transformation choose an XslTransformFile using the file selector. 14. Click yes to the dialog to generate a new schema. 15. Click the button in the XPathToItem field to open the XPath selector dialog to choose an element for the data item. Highlight the required element and select OK. 16. Selecting an element will generate new Field nodes for each possible child element and attribute of the data item element. 17. Edit the fields as required. Every data connection provider must always have an ID and Title field. 18. Remove fields that will not be used in the detail view or in relationships. 19. Create Relationship Types as required. 20. If required change the xml data and/or xml transformation file location to be a URL or a filename relative to the configuration directory. Xml Data Connection Settings MinutesToCache XmlDataFile XPathToItem The duration that the xml data file and transform file should be cached for. The path to the xml data file. The file can be specified by URL, absolute file path or a file path relative to the web application directory. The XPath that identifies a data item with the file. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 34

35 XslTranformFile The path to the xml transform (XSL) file used to transform the xml data file before data queries are performed. The file can be specified by URL, absolute file path or a file path relative to the web application directory. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 35

36 History Providers A history provider is responsible for saving and retrieving items that a user selects from a data connection. To create a new History Provider right click on the History Providers node and select New > Provider. Available history providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration and a specific provider on a data connection. No History Provider The No History provider takes no action with history requests and can be used to disable history functionality. Logging History Provider The Logging History provider logs all history requests and enables application tracing. Location Providers A location provider is responsible for retrieving information about, and the content of, a resource being labelled using Item Selector dialog and extender controls. To create a new Location Provider right click on the Location Providers node and select New > Provider. Available location providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration. Url Filters control which location provider is used to provide information and content for which url resource. If the match filters do not return a location provider then the default location provider is used. To add a new Url filter to a location provider right click on the Url Filters node within the location provider selector and select New > condition type. The conditions available will be determined by the DataConnect extensions currently installed. The core Url filters available are: And Not Or Page Url Enables a logical And to be performed on a set of rules. To add rules right click on the And node and click New. The And rule returns true if all the rules within the condition return true. Enables a logical Not to be performed on a rule. To add a rule, right click on the Not node and click New. The Not rule returns true if the rule within the condition returns false. Enables a logical Or to be performed on a set of rules. To add rules right click on the Or node and click New. The Or rule returns true if all one or more rules within the condition return true. Enables selection of specific pages within a web application based on the page url. At runtime the filter rule executes a comparison using the supplied MatchText against the context url provided. Available match types are Regular Expression (RegExp), Starts With, Ends With, Contains and Exact. For more information on Regular Expressions visit metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 36

37 For example to select all product.aspx pages set the MatchTest to product.aspx and the MatchType to Contains. Web Location Provider The web location provider returns the content available at the context url. Suggestion Providers A suggestion provider is responsible for suggesting items to label a specific resource. To create a new Suggestion Provider right click on the Suggestion Providers node and select New > Provider. Available suggestion providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration and a specific provider on a data connection. No Suggestion Provider The No Suggestion provider takes no action with suggestion requests and can be used to disable suggestion functionality. Logging Suggestion Provider The Logging Suggestion provider logs all suggestion requests and enables application tracing. It attempts to save the content of a resource passed to the suggestion provider into c:\window\temp. This can be used to validate the operation of the current Location Provider to retrieve content. User Providers A user provider is responsible for retrieving information about a user labelling a resource using Item Selector dialog and extender controls. To create a new User Provider right click on the User Providers node and select New > Provider. Available user providers will be dependent on your installation environment. After creation the provider will be available for selection as the default provider for the application configuration. Windows User Provider The Windows User provider returns the current ASP.Net Authenticated user if available and if not returns the current windows user. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 37

38 Building metaengine DataConnect for SharePoint configurations SharePoint List Data Connection To create a new SharePoint List Data Connection right click on the Data Connections node and select New > SharePointListData. Fill in the core data connection provider properties as described in the metaengine DataConnect Configuration Guide. Then complete the specific SharePoint List data connection properties. SharePoint List Data Connection Settings SharePointItemsList The name of the SharePoint list. SharePointWebUrl The URL to the SharePoint web site containing the list. Fields and Relationship Types are created dynamically at runtime using the schema of the list and cannot be edited in the Designer. A field is created for each SharePoint list field and a relationship type is created for each SharePoint lookup column in the list that references its own list. Single select Lookup columns create hierarchical relationship types and Multiple select Lookup columns create non- hierarchical relationship types. History Providers A history provider is responsible for saving and retrieving items that a user selects from a data connection. To create a new SharePoint History Provider right click on the History Providers node and select New > SharePointHistory. Location Providers A location provider is responsible for retrieving information about, and the content of, a resource being labelled using Item Selector dialog and extender controls. To create a new SharePoint Location Provider right click on the Location Providers node and select New > SharePointLocation. Suggestion Providers A suggestion provider is responsible for suggesting items to label a specific resource. To create a new SharePoint Suggestion Provider right click on the Suggestion Providers node and select New > SharePointSuggestions. metaengine DataConnect for SharePoint 2007 Configuration Guide (2.4) Page 38