Welcome to the Seeq Connector SDK!
This SDK is intended for developers that wish to write a Seeq datasource connector that can be loaded by a Seeq agent and facilitate access to data in Seeq.
Seeq connectors can be written in Java or C#. Java development can occur on Windows, OSX or Ubuntu operating systems. C# development requires Windows.
It is recommended that you initially develop with a "private" version of Seeq Server that is unrelated to your production or official testing systems. You should install this private version directly on your development machine to minimize the amount of initial setup and troubleshooting.
Install the version of Seeq Server that matches the version of the Connector SDK that you are using.
If you need a license file for this purpose, log a support ticket.
The Java version of the SDK is located in the java
directory and is built with Gradle. We recommend that you
familiarize yourself with the basics of Gradle before proceeding.
Before doing anything else, we recommend that you build the connector template and ensure that it is fully working with your private system.
From the java
directory, execute the build
command. This command will download dependencies from the web, so make
sure you have a good internet connection. If it fails for some (non-obvious) reason,
log a support ticket (include the error message).
Make sure your private Seeq Server is running on this machine.
IntelliJ IDEA is the recommended Integrated Development Environment (IDE) to use for developing and debugging your connector. You can use the free IntelliJ IDEA Community Edition.
Previous versions of the Seeq Connector SDK recommended and utilized Eclipse and the Maven build system. This version uses the Gradle build system and support for Gradle in Eclipse is not strong enough to recommend as an IDE for your connector.
Import the project into IntelliJ IDEA by taking the following steps:
On the left-hand side of the screen, you will see a Project tab and there will be a bolded java [seeq-connector-sdk] folder at the top level. There should be a small light-blue square in the bottom-right of the folder icon, which indicates that it was recognized as a Gradle project.
The Build tab at the bottom should eventually print BUILD SUCCESSFUL
to indicate that the Gradle project was built
correctly.
If you encounter Gradle build errors, verify that Gradle is using the correct JVM. In your IntelliJ Settings, go to
Build, Execution, Deployment > Build Tools > Gradle and select Add JDK in the dropdown menu for Gradle JVM. In the
popup for setting the JDK home directory, select the java/jdk/files
directory.
Take the following steps to verify your debugging setup:
src/main/java/com/seeq/link/sdk/debugging/Main.java
file in the seeq-link-sdk-debugging-agent
project.main()
function.src/main/java/com/mycompany/seeq/link/connector/MyConnector.java
file in the
mycompany-seeq-link-connector-myconnector
and put a breakpoint on the first line of the initialize()
function.My Connector Type: My First Connection
in the list of connections, with 5000 items indexed.simulated
.Now you're ready to start development!
You will probably want to adjust the name and group of your connector. You can do so by using rename refactorings on the
classes and folders in your IDE. You'll also have to adjust ALL the settings.gradle.kts
and build.gradle.kts
files accordingly, including the one in the seeq-link-sdk-debugging-agent
folder. After renaming, you will need to
click the Reload All Gradle Projects button within the Gradle tool window.
Connectors are discovered at runtime using Java's ServiceLoader
mechanism. You'll find your connector registered under
src/main/resources/META-INF/services/com.seeq.link.sdk.interfaces.ConnectorV2
. Make sure this file contains the
correct class name. If you use rename refactoring in your IDE, it should update this file automatically.
You can add additional dependencies in the build.gradle.kts
file in your connector's folder.
Once you are ready to start developing, just open the MyConnector.java
and MyConnection.java
files in your IDE and
start reading through the heavily-annotated source code. The template connector uses a small class called
DatasourceSimulator
. You'll know you've removed all of the template-specific code when you can delete this file from
the project and still build without errors.
Any log messages you create using the log()
method on ConnectorServiceV2
and DatasourceConnectionServiceV2
will go
to the debug console and to the java/seeq-link-sdk-debugging-agent/build/log/jvm-debugging-agent.log
file.
When you are ready to deploy your connector to a production environment, execute the build
command. A zip file will be
created in the build/distributions
folder of your connector.
Copy this zip file to the Seeq Server you wish to deploy it to. Shut down the server and extract the contents of the zip
file into the plugins/connectors
folder within Seeq's data
folder. (The data folder is usually
C:\ProgramData\Seeq\data
on Windows and ~/.seeq/data
on Ubuntu and OSX.) You should end up with one new folder in
plugins/connectors
. For example, if you kept the default name for the connector, you would have a
plugins/connectors/mycompany-seeq-link-connector-myconnector
folder with a jar file inside.
Re-start Seeq Server and your connector should appear in the list of connections just as it had in your development environment.
Once deployed, log messages you create using the log()
method on ConnectorServiceV2
and DatasourceConnectionServiceV2
will go to log/jvm-link/jvm-link.log
file in the Seeq data folder.
The C# version of the SDK depends upon Microsoft Visual Studio for building and debugging. This SDK is tested with Microsoft Visual Studio 2015.
The C# SDK also depends on .NET version 4.8. When upgrading .NET, you may need to restart your machine for the new version to take effect.
To begin using the SDK:
csharp
directory within this SDK.environment
.Throughout this document, we will refer to the build environment, which is simply a command prompt or terminal window where you've executed the environment script as described.
Before doing anything else, we recommend that you build the connector template and ensure that it is fully working with your private system.
From your build environment, execute the build
command. If it fails for some (non-obvious) reason,
log a support ticket (include the error message).
Make sure your private Seeq Server is running on this machine.
From your build environment, execute the ide
command. This command will launch Microsoft Visual Studio (VS), which you
will use for development and debugging.
Take the following steps to confirm a properly configured development environment:
Seeq.Link.SDK.Debugging.Agent
project in Solution Explorer and
select Set as Startup Project.EntryPoint.cs
file in the Seeq.Link.SDK.Debugging.Agent
project.Main()
function.MyConnector.cs
file in the
MyCompany.Seeq.Link.Connector.MyConnector
and put a breakpoint on the first line of the Initialize()
function.
Because the connector is loaded dynamically, this breakpoint may appear broken until it is actually hit.My Connector Type: My First Connection
in the list of connections, with 5000 items indexed.simulated
.Now you're ready to start development!
Troubleshooting hint: Within the connector project in the SDK folder, there should be a bin/Debug folder containing
a .pdb
file and a .dll
file as a result of building the solution. If these files are not present, it will not be
possible to debug the connector.
We recommend that you just modify the template connector directly. This shields you from having to recreate all of the configuration that is required to correctly build and debug a new project. Visual Studio has excellent renaming/refactoring features that make it easy. For example, you can click on any item in VS's Solution Explorer and press F2 to change it to something appropriate for your company and this particular connector.
Once you are ready to start developing, just open the MyConnector.cs
and MyConnection.cs
files in VS and start
reading through the heavily-annotated source code. The template connector uses a small class called
DatasourceSimulator
. You'll know you've removed all of the template-specific code when you can delete this file from
the project and still build without errors.
Any log messages you create using the Log
property on ConnectorServiceV2
and DatasourceConnectionServiceV2
will go
to the console window and to the csharp/Seeq.Link.SDK.Debugging.Agent/bin/Debug/log/net-debugging-agent.log
file.
When you are ready to deploy your connector to a production environment, execute the package
command. A zip file will
be created in the csharp/packages
folder.
Copy this zip file to the Seeq Server you wish to deploy it to. Shut down the server and extract the contents of the zip
file into the plugins/connectors
folder within Seeq's data
folder. (The data folder is usually
C:\ProgramData\Seeq\data
.) You should end up with one new folder in plugins/connectors
. For example, if you kept the
default name for the connector, you would have a
plugins/connectors/MyCompany.Seeq.Link.Connector.MyConnector
folder with DLLs inside.
Re-start Seeq Server and your connector should appear in the list of connections just as it had in your development environment.
Once deployed, log messages you create using the Log
property on ConnectorServiceV2
and
DatasourceConnectionServiceV2
will go to log\net-link.log
file in the Seeq data folder.
If you use the template connector project, your connector DLL will be compiled using the Any CPU
architecture, which
means it can be loaded by a 64-bit or 32-bit .NET Agent. If you have a dependency on an architecture-specific library
(most often that means the library is x86
) you may have to change the platform of your connector DLL to be x86
(or x64
in rare cases). If you do that, then your connector can only be loaded by a 32-bit .NET Agent, which means it
will have to be a Remote Agent. Contact Seeq Support for more information.