Integrating ThingWorx with third-party systems (Software or Hardware Devices) - Comprehensive Guide

[#1]

One of topics that are usually of interest when entering the ThingWorx world is integration with third-party systems.

Disclaimer: the following guide is intended to be rather comprehensive and guide you in achieving the best integration with your desired system ( !=quick and dirty ).

For example, from my experience, customers many times ask:

-how can I connect to my hardware device

-how can I connect to this device cloud so I can get data from it?

-how can I connect to my ERP?

With some luck, I hope that at the end of this article I will provide a generic workflow that will help you on achieving the best integration solution for your use-case.

We need to write down some requirements (they are not in order; depending on the usecase might not be worth to be answered):

0. What is the usecase (detailed description) ?.

     This is by far one of the most important aspects of any software development project.

     Please document your usecase with all possible future uses.

     For example:

          - I want to send information from sensors to the ThingWorx Server, and I want to do TCP Tunnelling to the device and/or Remote Desktop. Or maybe only sending information from sensors and nothing else. Do I need in the future Software Updates or not?

          - I want to read the Customer information from my CRM AND also update that information (read/write).

1. Write down system specification for the hardware or software system.

          -Available RAM for user apps

          -Available Disk Space for User Apps

          -Does it have a TCP IP Stack?

          -Operating System

          -Installed runtimes (Java/.NET - which versions?)

2. Can I access the system or device directly from the ThingWorx Server?

     This means answering the question: is my system directly accessible from my server? Or is there a firewall which stops incoming connections?

     Another question to answer, is: can I modify my firewall to allow incoming connections?

3. What protocol is my device or system capable of supporting for data transfer?

     Example: I have a device which is capable of outputting information through TCP only.

                    I have a device who can only do HTTP callbacks to a HTTP server.

                    I have Microsoft SQL, to which I can connect through ADO.NET or JDBC.

                    I have a third party service billing provider who supports interfacing via HTTP Webservices (SOAP or REST).

                    I have a device supporting CoAP.

     Typically all third party software systems support communication via Webservices.

4. Can I configure and/or deploy new software to my device or system?

     We need to have this question answered, because on some cases it might make more sense to write some logic on the system or device.

     For example if I want to access data from an SQL server and my usecase might require some processing for which that SQL server is better suited to do, it might be much more efficient to have that logic stored as a Stored Procedure there and I just call it from ThingWorx.

      Or in the case of Windchill, it might make more sense to write an InfoEngine task to do my functionality than writing that on the ThingWorx side.

     Possible example answers:

                    -My device is already deployed in the field and I can not modify the configuration at all.

                    -My device is a new product, so I can put whatever software I want on it.

                    -I only have read access to my software system, so I must do all processing externally.

If you wrote down all of those it is time to determine what are the integration options for us.

The typical workflow that I follow is the next one: I look for any Out-Of-The-Box supported protocol (determined at step 3) and then implement the needed functionality in the language that is best suited for my usecase (Javascript usually).

The list of protocols that the platform supports is listed in different places:

-PTC Help Center Link

-ThingWorx Marketplace - https://marketplace.thingworx.com/items

The key point is that the list is alive and updated by both our partners and us.

Usually the preferred way to write logic is by using the Javascript services. It makes it incredibly fast to write down your business logic without having the need to recompile.

The elements from the ThingWorx ecosystems that we can use are the following:

-the ThingWorx server itself (it has built in support for calling external Webservices)

-ThingWorx Extensions. They are Java written pieces of code that can help you achieve your usecase. To be used whenever your ThingWorx server OOTB functionality (or Marketplace Extensions) does not allow you to develop your usecase. There is no actual need to write an Extension if somebody else already developed that for you and published in the ThingWorx Marketplace https://marketplace.thingworx.com/items

     A link for understanding Extension is the following: How to rapidly develop ThingWorx IIoT Extensions

-ThingWorx Integration Connectors

-ThingWorx Edge Micro Server: https://developer.thingworx.com/ems

-ThingWorx Edge SDKs: https://developer.thingworx.com/sdks

Examples:

-I have an third party Server which allows me to send SMS and Voice messages through it via its Rest API.

     Answer: best here is to use the OOTB Webservices support from ThingWorx, which exposes the HTTP verbs, like GET, POST, PUT, via the ContentLoaderFunctions

-I have a device which has a TCP stack that is capable only to do HTTP calls.

     Answer: I can point that device to do calls against the REST API of ThingWorx, in order to update data directly there.

-I have a fleet of 300.000 devices which are sending their data to an MQTT server.

     Answer: In this case I can use the MQTT Extension that is offered by ThingWorx

-I have an external SQL server that does not accept inbound connections (behind a firewall) but I must get data from it. Network will however allow outbound connections

     Answer: use the ADO.NET Edge Client that must be installed in a location accessible to that server. The ADO.NET Edge Client will connect to the Server and then to the ThingWorx platform allowing use of SQL statements directly from within the platform.

-I have a device who only accepts TCP connections and I want to read data from it. It sends data only after receiving a command through TCP.

     Answer: Use the TCP Extension available in the ThingWorx Marketplace. It is built specifically for this usecase

-I have a device which has lots of RAM and Disk Space and I must send data from it, while allowing software updates in the future.

     Answer: depending on your preferred coding language you can use either the ThingWorx Edge Microserver (for which you must write code in LUA) or write an implementation in one of the ThingWorx Edge SDKs. A key point here is to understand that the coding effort is identical in theory, and is only limited by the experience you have and the functionality that may be available easier in Java, vs LUA, vs C, vs. Net.

I appreciate feedback to this article in the hope of being able to continuously improve it.

[mkhalil1]

Many Thanks for this summary
Now, i have NB-IOT KIT that support AT-Commands , it is runing with UDP COAP protocol
what are the parameters that are mandatory to be set on device side to communicate with platform?

can you please share some examples to use AT Command with COAP connecting to ThingWorx?

[VladimirRosu]

Hi Mohamed,

First a disclaimer: I am not the expert in CoAP.

I don't think that you need to set any device parameters on the device side.

The ThingWorx platform will interact with the CoAP server that the device is already using.

There is an extension in the marketplace that helps you achieving this purpose: https://marketplace.thingworx.com/Items/coap-extension

The Extension does not contain a CoAP server (and neither the ThingWorx platform).

There is also another possibility, to embed into a ThingWorx Extension (or an Edge SDK implementation) a CoAP server, so you don't need to span CoAP server somewhere else (that is valid if you don't already have a CoAP server somewhere)

Hope it helps,

Vladimir