ThingWorx Relational Databases Connectors Extension User Guide Version 1.0
Software Change Log... 2 Introduction and Installation... 2 About the Relational Databases Connectors Extension... 2 Installing the Relational Databases Connectors Extension... 2 Configuration and Usage... 4 Configuration... 4 Usage... 5 Known Limitations and Compatibility... 6 Document Revision History... 7 1
Software Change Log Version Release Date Changes 1.0 1/15/2016 Initial Release Introduction and Installation Extensibility is a core aspect of the architecture and design of ThingWorx. Partners, third parties, and general ThingWorx users can easily add new functionality into the system, seamlessly. Extensions can be in the form of service (function/method) libraries, connector templates, widgets, and more. This document provides installation and usage instructions for the Relational Databases Connectors Extension. About the Relational Databases Connectors Extension The Relational Databases Connectors Extension provides the means to connect to the most popular relational database servers: - Oracle Database versions: 11, 12 - MySQL versions: 4.1, 5.0, 5.1, 5.5, 5.6, 5.7 - Microsoft SQL versions: 2008, 2012, 2014 - PostgreSQL versions: 7.2 and newer - IBM DB2 versions: 10.1, 10.5 The Relational Databases Connectors Extension for the ThingWorx Platform provides thing templates to enable you to connect to the most popular relational database servers. Using these templates in ThingWorx Composer, you can create connector things that configure a connection to a supported relational database server. To interact with the database server, you can write services for these things, using Javascript, or SQL queries and commands. Installing the Relational Databases Connectors Extension 1. From a web browser, launch ThingWorx Composer. 2. Log into ThingWorx Composer as an administrator. 2
3. Go to Import/Export > Import. 4. Click Choose File and select RelationalDBConnectors_Extension.zip 5. Click Import. Note: If an Import Successful message does not appear, contact your ThingWorx System Administrator. 6. Click Yes to refresh Composer after importing the final extension. 3
7. Now the templates are available in the entities list. Configuration and Usage Usage of the Relational Databases Connectors Extension requires creation and configuration of a database connector thing for each type of database in ThingWorx Composer. The database connector things provide the capability to define SQL Queries and Commands to interact with the Database Server. Configuration When creating things that connect to Oracle or IBM databases, use the template that matches the version of the database, as shown in the following table: To connect to Version Use this thing template Oracle Database Server 11 OracleDBServer11 12 OracleDBServer12 IBM DB 2 Server 10.1 DB2v101Server 10.5 DB2v105Server 4
For all supported databases, specify a username and password. The steps to configure the connection follow: 1. Once the thing is created, you must configure it to connect to an instance of the database server. Within the ThingWorx Composer, open up the new database thing. 2. Navigate to the Configuration section. 3. Under the JDBC settings, enter valid information for each of the connection parameters. The pre entered values are suited for each database server, so you can use them as examples or replace the hostname, port, database/schema name, username, and password. 4. Configure the settings for monitoring connections. 5. Provide column aliases to use in the SQL Queries and Commands. Usage You can use the Relational Database Connectors Extension to write SQL Queries and Commands to interact with the Database Server. When creating a new service on the thing, you can choose the type. 5
The SQL Query and Command service types should contain SQL syntax and can have declared input parameters and output, just like a Javascript service. 6
Known Limitations and Compatibility Supported databases and its versions are mentioned in the section About the Relational Databases Connectors Extension. Any other databases or versions are not supported by this extension. The following note targets just the PostgreSQL Extension contained in the Relational DB Connectors extension. If you have a ThingWorx server with PostgreSQL Database, before importing the Relational DB Connector extension (or just the PostgreSQL connector extension which is inside the Relational DB Connectors extension) you need to remove the PostgreSQL JDBC driver jar file from this extension to avoid conflicts when importing, by doing the following: - From the extension archive, remove the PostgreSQL_Extension.zip/lib/common/postgresql 9.4 1201.jdbc4.jar file - In the ThingWorx installation directory (locate the Tomcat installation then go to webapps/thingworx) go to WEB INF/lib and locate a file named like the one you deleted from the extension (eg: postgresql *** jdbc*.jar). If the name is different than the one you deleted previously from the extension (this one: postgresql 9.4 1201 jdbc4.jar), then proceed to the next step. If not, you are done and you can import the extension. - Last, you have to make sure an existing (inside the Thingworx lib folder) PostgreSQL JDBC driver jar file is referenced in the PostgreSQL extension metadata.xml file. So, open the extension archive and edit the PostgreSQL_Extension.zip/metadata.xml file, by replacing at line #9 the name of the jar file (postgresql 9.4 1201.jdbc4.jar) you deleted previously with the one you found in the <Thingworx_Home>/WEB INF/lib folder (which is already in the Thingworx library). Now you are done and you can import the extension. 7
The current version of this extension has been tested for compatibility with the following versions of the ThingWorx Platform and Java JRE: 8
ThingWorx Platform Version Java JRE Version ThingWorx 6.5.0 Java version 7, update 60 ThingWorx 6.6.2 Java version 8, update 66 Document Revision History Revision Date Version Description of Change January 15, 2016 1.0 Initial release 9