thingworx-connect
A library used to make REST API calls to Thingworx from Node and frontend JavaScript in a Thingworx-ish way. You can call entities' services and get and set their properties.
Installation
Install it through npm:
npm i thingworx-connect
Or download one of the stand-alone flavors (for frontend usage):
- Uncompressed, development version: thingworx-connect.umd.js
- Minified, production version: thingworx-connect.umd.min.js
Important note for browser users
If applicable, please make sure that you enable CORS on the Thingworx server(s) you plan to make requests to. If you don't have admin access to the server, or don't know what I am talking about, you can always use a CORS proxy. I recommend using this one: cors-proxy
Usage
Either import the library using an ES6 import (for browsers and web bundlers such as Webpack and Rollup.js):
;
Or using a CommonJS import (Node):
const Thingworx = ;
Or include it with a <script>
tag (for browser usage):
Browser usage
You can start making REST API calls to Thingworx right away! Simply pass in your server url to the .collections()
method of the Thingworx
object.
If your server url's protocol is http
, you can omit it. Similarly, if the port is 80
, you can also omit it.
{ const Things ThingTemplates = Thingworx; /* Reading properties */ const myProperty = await Things'MyThing'myProperty; /* Setting properties */ // Make sure you specify the correct property type. In this example, // myProperty is of basetype STRING. await Things'MyThing'myProperty; /* Calling services */ // This will return a single value, be it a number, boolean, string, date, etc.. const squareRoot = await Things'MathUtils'; // This will return a json of the shape: { dataShape: { fieldDefinitions: {} }, rows: [] }, // just as Thingworx infotables. const infoTable = await ThingTemplates'GenericThing'; // This will return only the rows of the resulting infotable, droping down the datashape. // If any of the infotable fields is also an infotable, that nested infotable will also have its datashape dropped. const infoTableRows = await Things'MyThing'rows; // This will return a json. const json = await Things'Utilities'; // This will return undefined await Resources'EntityServices';}
When calling .collections()
, the browser will ask for your credentials when you make the first request.
You can also pass in the app key:
const Things = Thingworx;
or your username and password:
const Things = Thingworx;
You can guarantee that two calls to the .collections()
method with the same parameters (server url and authentication paramaters) will return the same object. That is,
const collections1 = Thingworx;const collections2 = Thingworx;console; // Will output 'true' const collections3 = Thingworx;const collections4 = Thingworx;console; // Will also output 'true'
Every time you call the .collections()
, the library checks if there has been a call to the method wih the same parameters before, and if so, returns the cached result.
There is also another flavor of the .collections()
method, namely the .mutableCollections()
method.
The advantage is that with this flavor, you can change the authentication parameters later on.
For example, given this:
const mutableCollections = Thingworx;const Resources Users Things = mutableCollections;
We can do this:
{ // This will print 'myself' const currentUsername = await Resources'CurrentSessionInfo'; console; // This will print 'otherUser' mutableCollections; const username2ndAttempt = await Resources'CurrentSessionInfo'; console;}
Or more crazy stuff:
{ await Users'myself'; // this will throw a 401 error await Things'MyThing'; // However this will perfectly work mutableCollections; await Things'MyThing'; // success!}
The disadvantage of using .mutableCollections()
is that every time you call the method, a new set of collections is created (in contrast to the .collections()
method). That is,
const collections1 = Thingworx;const collections2 = Thingworx;console; // Will output 'false' const collections3 = Thingworx;const collections4 = Thingworx;console; // Will also output 'false'
Important information for Node users
The usage instructions for Node are the same as the browser usage instructions, except for one thing:
Since Node does not support cookies or credentials (because it is backend), you forcefully need to pass either the
appKey or the username and password to the .collections()
and .mutableCollections()
method:
const Things = Thingworx;
or
const Things = Thingworx;