There are lots of connectors that get installed with OneView Connect, both the standard installation and the enterprise installation.  But what if you had a system that none of these connectors quite worked for.  Well, we have opened our OneView Connect product to developers through our API.  So, now you can create your own custom connectors to connect to any system you have access to - to get that data.

This post will get you familiar with what building on the OneView Connect framework will give you, including accessing OneView properties and parameters, and once you’ve connected to your data, rendering that data in the web part.

In just 5 easy steps, I'm going to show you how to create a simple custom connector.  We'll build a text file connector to connect to a text file and read the data from it.

Let’s get started.

1.      Inherit from the OneView.Data.Connector

Inherits OneView.Data.Connector

By inheriting from this class, you open up your code to all of the functionality of all of our other OneView Connectors.  You get access to our web based Configuration Editor as well as access to the properties & parameter collections.  Everything you can do with a OneView connector, you can now do with your custom connector.

2.      Override required and optional methods

When creating your own custom connector, at a minimum, all you would need to do is call some code that returns a dataset in the GetDataset function and you have just created your own custom connector.  If you stopped right there, built and deployed, the dataset will now be available to the OneView web parts through this connector.  In the below example code, calling the “TextToDataSet” function returns data from a text file. 

Public Overrides Function GetDataset(ByVal dsd As DataSource) As System.Data.DataSet

 

        ' check for missing or required settings

        ValidateSettings(dsd)

 

        ' get the settings from web part configuration editor

        Dim file As String = dsd.Settings("file")

        Dim delimiter As String = dsd.Settings("delimiter", ";")

        Dim tableName As String = dsd.Settings("tablename", "results")

 

        ' create new dataset and load from a specified text file

        Dim ds As DataSet = TextToDataSet.Convert(file, tableName, delimiter)

 

        ' return dataset to OneView Connect framework

        Return ds

End Function

In my example, I have added code to get the settings from the Web Part Configuration Editor by overriding the DatasourceSettings Class.

Public Overrides ReadOnly Property DataSourceSettings() As SettingCollection

        Get

            ' this is where you can pre-populate list of required or

'  optional DataSource(settings)

 

            ' Return MyBase.DataSourceSettings

 

            Dim setting As Setting

            Dim defaults As New SettingCollection

 

            setting = New Setting("file")

            setting.SetRequired = True

            defaults.Add(setting)

 

            setting = New Setting("delimiter")

            setting.SetRequired = False

            setting.SetDefaultValue = ";"

            defaults.Add(setting)

 

            setting = New Setting("tablename")

            setting.SetRequired = False

            setting.SetDefaultValue = "Results"

            defaults.Add(setting)

 

            Return defaults

   End Get
End Property

How you define your data source is what gives you the greatest amount of flexibility.  You can literally define any number of custom settings to control how your web part connects to and uses your data.

In the above example, I am defining my datasource by requiring that the user provide the “file”, i.e. where the text file is located.  I am also adding two optional settings, “delimiter” and “tablename”.  The delimiter the user provides is the delimiter in the text file that defines the tables and rows for the dataset.  I’ve also added an example “tablename” optional setting.

Other functions you can override in your connector code are the GetTable, GetTableColumns and ValidateSettings.

'Optional.  You can return a datatable optimized for this connector.  If you don't override this function, it will return table(0) from GetDataset

Public Overrides Function GetTable(ByVal dsd As DataSource) As System.Data.DataTable

        Return MyBase.GetTable(dsd)

    End Function

 

'Optional.  You can return a columns collection optimized for this connector.  If you don't override this function, it will return tables(0).columns from GetDataset

Public Overrides Function GetTableColumns(ByVal dsd As DataSource) As System.Data.DataColumnCollection

        Return MyBase.GetTableColumns(dsd)

    End Function

 

'Optional.  You can check ds.Settings collection for required values, etc.  If you don't override this function, it will will loop through DataSourceSettings collection and do the same

Public Overrides Function ValidateSettings(ByRef ds As DataSource) As Boolean

    Return MyBase.ValidateSettings(ds)

End Function

3.      Strong name and deploy to GAC

Web parts should have a strong name when used in SharePoint.  If you do not already have a .snk file in your project, you can create a new one in Visual Studio. 

1. Right-click on your project and select Properties
2. Select the Signing option
3. In the drop down list, select the option <New> or insert your own if you already have one
4. Type in a Key File Name (e.g. keypair.snk)
5. Uncheck the Protect my key file with a password option
6. Click OK
7. The keypair.snk file will be added to the project

Rebuild your project and deploy the assembly to the Global Assembly Cache (GAC).

For more information on deploying web parts in Sharepoint and security permissions considerations, see Deploying Web Parts in Windows SharePoint Services  on MSDN; on deploying assemblies to the GAC, see Basic Instincts, Deploying Assemblies by Ted Pattison.  Also note that whenever you deploy to the GAC, you must run an IISReset.

4.      Register your new connector in the OneView Connector Catalog

Before you can use your new connector, you must register it in the OneView Connector Catalog.  To do this, you import a Connector Settings file and import it into the OneView Connector Catalog.

a)       Create a Connector Settings File.

To create a connector settings file, you must provide at a minimum, a display name for your connector, the assembly information and any connector settings.  Below is the connector file for the TextFileConnector example above.

Note: You can get your public key token by right clicking on your assembly file in the GAC and copying it from there.

<Connectors>

<Connector>

<DisplayName>Text File Connector</DisplayName>

<Description>Connect to a delimited text file</Description>

<AssemblyName>OneView.Examples.TextFileConnector, OneView.Examples, Version=1.0.0.0, Culture=neutral, PublicKeyToken=821ad494ef90d13d</AssemblyName>

<ConnectorSettings>

<Setting Name="Example Setting 1" Value="Value1" />

<Setting Name="Example Setting 2" Value="Value2" />

</ConnectorSettings>

</Connector>

</Connectors>

Note: we did not use the <ConnectorSettings> section in the above example, I have included it in this xml file only as an example.  This section would be used to create custom settings for your connector that you would want available through the Central Administration site only and not through the web part Configuration Editor.

b)      Import your Connector Settings File

1.       Go to Application Management in Central Administration

2.       Click Manage Connectors under the OneView Connect section.

3.       Click Import Connectors and browse to your Connector Settings xml file.

4.       Click Import

Your connector is now available in the OneView Connector Catalog. 

To edit your connector, simply select “Edit Connector Settings” from the context menu.

These are the settings created in your Connector Settings xml file in the previous step.  To modify the connector settings – take away a setting or add more – simply edit your xml file and re-import it making sure to check the “overwrite existing connector(s)” check box.

Your connector is now available for use in any of the OneView Connect web parts.

Using the connector

All connectors require a Connection String, a way to connect to your data, and a Query, a way to query your data.  For the above example, the Connection String consists of our custom datasource settings.  The following syntax is used to provide our “connection string”: Setting=”[settingvalue];”, so for the example above, the connection string is: file="c:\temp\data1.txt";delimiter=";"; 

This will connect and query the text file rendering the data in the web part.

5.      Build something useful!

Using these same basic principles you can now build your own connector to connect to any disparate data source you may have.  Rendering the data is no different than rendering data in any of the available OneView Connect web parts.  If you want a straight list, use the OneView Connect List Web Part, if you want more control over the look of your data, use the OneView Connect XML web part and create custom xsl to render your data any way you choose.

All properties available to the OneView web parts are still available when using your custom connector.  That goes for the use of parameters as well.  For more information on OneView properties and parameters, please refer to the OneView Connect Administration Guide.

Final Thoughts

Exposing our base classes through our API gives developers a powerful set of tools to build upon.  There are just a few best practices to keep in mind when building custom connectors.

• Minimally override GetDataset, but optimize GetTable and GetTableColumns as needed
  
•   When accessing raw XML, class must be marked serializable; Implement IXMLConnector interface to expose raw XML
  
• Connectors must expose a constructor without parameters; you can overload with parameters if desired
  
• Always use SharePoint web part development and SharePoint debugging best practices

I hope this has been a useful exercise for you.  Let us know how you’re using your own custom connectors – we’d love to hear from you.

OneView.Examples.zip