cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Community Tip - When posting, your subject should be specific and summarize your question. Here are some additional tips on asking a great question. X

IoT Tips

Sort by:
    Keys to utilizing the C and Java SDK for ThingWorx application development   GUIDE CONCEPT   This project will introduce to coding examples utilized for SDKs to be used with Java and C. You can also use the Java SDK for Android development.   Following the steps in this guide, you will be better prepared to creating your own application using one of our SDKs.   We will teach you how to handle Properties, Entities, data, make Service calls and creating Remote Services.     YOU'LL LEARN HOW TO   How to create, update, and retrieve Property values Utilize Data Shapes for handling data and triggering Events Construct Info Tables for Services and retrieving data after Service calls Add key features of an edge/remote application   NOTE: The estimated time to complete this guide is 30 minutes.     Step 1: Connection Process   he ThingWorx SDKs follows a three-step process when connecting to the ThingWorx Platform.   NOTE: In this context, Client refers to the application and the SDK running on the device and Server refers to the ThingWorx Platform.   Websocket   The client opens a Websocket to the server using the host and port. With the ThingWorx platform you can connect via HTTP and HTTPS with access to Services, Properties, Events, Entities, and Resources.   Authentication   In order to connect and access information from the server, you must utilize an authorization method. Application Keys provide a secure method for the SDK to log into the platform and perform transactions. The client sends an authentication message to the server containing an Application Key.   Binding   Binding is an optional step in the client connection process. The SDK client allows one or more VirtualThings to be associated with a Websocket connection, using their names or identifiers. Binding a property in your ThingWorx application to that of your source code provides several benefits, including being able to update properties while offline.     Click here to view Part 2 of this guide.
View full tip
  Connect Devices and Equipment Using Industry-Standard Protocol Drivers in ThingWorx   GUIDE CONCEPT   This guide has step-by-step instructions for connecting ThingWorx Kepware Server to ThingWorx Foundation.   This guide will demonstrate the ease of connecting edge industrial equipment to ThingWorx Foundation without installing any software on production equipment.   We will also show how connecting different systems and devices improves operations through the creation of business intelligence.     YOU'LL LEARN HOW TO   Connect ThingWorx Kepware Server to ThingWorx Foundation Secure the connection with an Application Key Create an IndustrialGateway Thing Map ThingWorx Kepware Server Tags to ThingWorx Foundation Thing Properties Visualize Data from connected digital assets   Note: The estimated time to complete this guide is 30 minutes     Step 1: Installation   Download the ThingWorx Kepware Server executable application from MyKepware. If you desire installation instructions, you may find them in the attached guide: install-thingworx-kepware-server.zip . Navigate to START -> PTC. Click ThingWorx Kepware Server 6 Configuration.                           For additional information on ThingWorx Kepware Server, click Help -> Server Help on the Menu Bar.         Step 2: Create Gateway   To make a connection between ThingWorx Kepware Server and Foundation Server, you must first create a Thing.   WARNING: To avoid a timeout error, create a Thing in ThingWorx Foundation BEFORE attempting to make the connection in ThingWorx Kepware Server.   In ThingWorx Foundation Composer, click Browse > Modeling -> Things.   Click + NEW. In the Name field, type IndConn_Server, including matching capitalization. In the Description field, enter an appropriate description, such as Industrial Gateway Thing to connect to ThingWorx Kepware Server. If the Project field is not already set, search for and select PTCDefaultProject. In the Base Thing Template field, search for and select IndustrialGateway.   Click Save.     Step 3: Create an AppKey   To secure the connection between ThingWorx Foundation and ThingWorx Kepware Server, you need to utilize an Application Key.   In ThingWorx Foundation, click Browse > Security -> Applications Keys.   Click + New. In the Name field, type IndConn_AppKey. If Project is not already set, search for and select PTCDefaultProject. Set User Name Reference to the Administrator User. Click Yes on the warning pop-up.   Assign an Expiration Date that is far enough in the future to not interfere with your trial.   Click Save.   Under Key ID, click the page icon to the right of the Application Key string to copy it.     Step 4: Connect to Foundation   Now that you’ve created an IndustrialGateway Thing and an Application Key, you can configure ThingWorx Kepware Server to connect to ThingWorx Foundation.   Return to the ThingWorx Kepware Server Windows application. Right-click Project. Select Properties….   In the Property Editor pop-up, click ThingWorx. In the Enable field, select Yes from the drop-down. In the Host field, enter the IP address or URL of your ThingWorx Foundation server. Enter the Port number. If you are using the "hosted" Developer Portal trial, enter 443.     In the Application Key field, copy and paste the Application Key you just created. In the Trust self-signed certificates field, select Yes from the drop-down. In the Trust all certificates field, select Yes from the drop-down. In the Disable encryption field, select No from the drop-down if you are using a secure port. Select Yes if you are using an http port. Type IndConn_Server in the Thing name field, including matching capitalization. If you are connecting with a remote instance of ThingWorx Foundation and you expect any breaks or latency in your connection, enable Store and Forward. Click Apply in the pop-up. Click Ok.   In the ThingWorx Kepware Server Event window at the bottom, you should see a message indicating Connected to ThingWorx.     NOTE: If you do not see the "Connected" message, repeat the steps above, ensuring that all information is correct. In particular, check the Host, Port, and Thing name fields for errors.     Click here to view Part 2 of this guide.
View full tip
    Step 7: Widget Lifecycle at Runtime   When a Widget is first created, the runtime will obtain any declared Properties by calling the runtimeProperties() function.   The property values that were saved in the Mashup definition will be loaded into your object without your code being called in any way. After the Widget is loaded but before it’s displayed on the screen, the runtime will call renderHtml() for you to return the HTML for your object. The runtime will render that HTML into the appropriate place in the DOM. Immediately after that HTML is added to the DOM, you will be called with afterRender(). This is the time to do the various jQuery bindings (if you need any). It is only at this point that you can reference the actual DOM elements, and you should only do this using code such as:   // note that this is a jQuery object var widgetElement = this.domElement;   This is important because the runtime actually changes your DOM element ID (domElementId) and you should never rely on any ID other than the ID returned from this.   If you have defined an event that can be bound, whenever that event occurs, you should call the following:   var widgetElement = this.domElement; // change ‘Clicked’ to be whatever your event name is that // you defined in your runtimeProperties that people bind to widgetElement.triggerHandler('Clicked'); 4. If you have any properties bound as data targets, you will be called with updateProperty(). You are expected to update the DOM directly if the changed property affects the DOM - this is likely, otherwise why would the data be bound. 5. If you have properties that are defined as data sources and they are bound, you can be called with getProperty_{propertyName}() …. If you don’t define this function, the runtime will simply get the value from the property bag.     Step 8: Runtime APIs available to Widgets   The following APIs can be accessed by a Widget in the context of the runtime:   this.jqElementId - This is the DOM element ID of your object after renderHtml(). this.jqElement - This is the jquery element. this.getProperty(name) - Accessor. this.setProperty(name,value) - Modifier. this.updateSelection(propertyName, selectedRowIndices) - Call this anytime your Widget changes selected rows on data that is bound to a certain propertyName. For example, in a callback for an event like onSelectStateChanged(), you would call this API and the system will update any other Widgets relying on selected rows.   Step 9: Runtime Callbacks   The following functions on the widget are called by the runtime.   runtimeProperties() - [optional] Returns a JSON structure defining the properties of this widget. Optional properties are:   isContainer - true or false (default to false); Controls whether an instance of this widget can be a container for other widget instances. needsDataLoadingAndError - true or false (defaults to false) - Set to true if you want your widget to display the standard 25% opacity when no data has been received and to turn red when there is an error retrieving data. borderWidth - If your widget provides a border, set this to the width of the border. This helps ensure pixel-perfect WYSIWG between builder and runtime. supportsAutoResize- If your widget supports auto-resize, set this to true. propertyAttributes – If you have STRING properties that are localizable, list them here. For example, if TooltipLabel1 is localizable:   this.runtimeProperties = function () { return { 'needsDataLoadingAndError': true, 'propertyAttributes': { 'TooltipLabel1': {'isLocalizable': true} } } };   renderHtml() [required] - Returns HTML fragment that runtime will place on the screen; the widget’s content container (e.g. div) must have a ‘widget- content’ class specified. After this container element is appended to the DOM, it becomes accessible via jqElement and its DOM element ID will be available in jqElementId. afterRender() [optional] - Called after the widget HTML fragment is inserted into the DOM. Use this domElementId to find the DOM element ID. Use this jqElement to use the jQuery reference to this DOM element. beforeDestroy() [optional but highly recommended] - This is called anytime the widget is unloaded. This is where to:   unbind any bindings clear any data set with .data() destroy any third-party libraries or plugins, call their destructors, etc. free any memory you allocated or are holding onto in closures by setting the variables to null There is no need to destroy the DOM elements inside the widget, they will be destroyed for you by the runtime. resize(width,height) [optional – Only useful if you declare supportsAutoResize: true] - This is called anytime the widget is resized. Some widgets don’t need to handle this, for example, if the widget’s elements and CSS auto-scale. But others (most widgets) need to actually do something to accommodate the widget changing size. handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) - Called whenever selectedRows has been modified by the data source you’re bound to on that PropertyName. selectedRows is an array of the actual data and selectedRowIndices is an array of the indices of the selected rows. Note: To get the full selectedRows event functionality without having to bind a list or grid widget, this function must be defined.   serviceInvoked(serviceName)- serviceInvoked() - Called whenever a service you defined is triggered. updateProperty(updatePropertyInfo) - updatePropertyInfo An object with the following JSON structure:   { DataShape: metadata for the rows returned ActualDataRows: actual Data Rows SourceProperty: SourceProperty TargetProperty: TargetProperty RawSinglePropertyValue: value of SourceProperty in the first row of ActualDataRows SinglePropertyValue: value of SourceProperty in the first row of ActualDataRows converted to the defined baseType of the target property [not implemented yet], SelectedRowIndices: an array of selected row indices IsBoundToSelectedRows: a Boolean letting you know if this is bound to SelectedRows }   For each data binding, the widget’s updateProperty() will be called every time the source data is changed. You need to check updatePropertyInfo. TargetProperty to determine what aspect of the widget needs to be updated. An example from thingworx.widget.image.js:   this.updateProperty = function (updatePropertyInfo) { // get the img inside our widget in the DOM var widgetElement = this.jqElement.find('img'); // if we're bound to a field in selected rows // and there are no selected rows, we'd overwrite the // default value if we didn't check here if (updatePropertyInfo.RawSinglePropertyValue !== undefined) { // see which TargetProperty is updated if (updatePropertyInfo.TargetProperty === 'sourceurl') { // SourceUrl updated - update the <img src=this.setProperty('sourceurl', updatePropertyInfo.SinglePropertyValue); widgetElement.attr("src", updatePropertyInfo.SinglePropertyValue); } else if (updatePropertyInfo.TargetProperty === 'alternatetext') { // AlternateText updated - update the <img alt= this.setProperty('alternatetext', updatePropertyInfo.SinglePropertyValue); widgetElement.attr("alt", updatePropertyInfo.SinglePropertyValue); } } };   NOTE: In the code above, we set a local copy of the property in our widget object, so if that property is bound as a data source for a parameter to a service call (or any other binding) - the runtime system can simply get the property from the property bag. Alternately, we could supply a custom getProperty_ {propertyName} method and store the value some other way.   getProperty_{propertyName}() - Anytime that the runtime needs a property value, it checks to see if the widget implements a function that overrides and gets the value of that property. This is used when the runtime is pulling data from the widget to populate parameters for a service call.     Click here to view Part 4 of this guide.
View full tip
  Quickly Build Mashup Widget Extensions and Extend Application Functionality with the Eclipse Plugin.   GUIDE CONCEPT   Extensions enable you to quickly and easily add new functionality to an IoT solution. Mashup widget extensions can be utilized to enhance a user's experience, your ability to develop robust applications, and make development easier as you move forward with your IoT development.   The Eclipse Plugin for ThingWorx Extension Development (Eclipse Plugin) is designed to streamline and enhance the creation of extensions for the ThingWorx Platform. The plugin makes it easier to develop and build extensions by automatically generating source files, annotations, and methods as well as updating the metadata file to ensure the extension can be imported.   These features allow you to focus on developing functionality in your extension, rather than spend unnecessary time getting the syntax and format of annotations and the metadata file correct.     YOU'LL LEARN HOW TO   Utilized the Eclipse Plugin and Extension SDK Create and configure an Extension project Create A mashup Widget Extension Build and import an Extension   NOTE: This guide's content aligns with ThingWorx 9.3. The estimated time to complete ALL parts of this guide is 60 minutes.     Step 1: Completed Example   Download the completed files for this tutorial: MashupWidgetSamples.zip. Download the Eclipse Plugin. Download Extensions SDK.   The MashupWidgetSamples.zip file provided to you contains a completed example of a simple Widget project and examples of more advanced widget source code. Utilize this file to see a finished example and return to it as a reference if you become stuck during this guide and need some extra help or clarification.   Keep in mind, this download uses the exact names for Entities used in this tutorial. If you would like to import this example and also create Entities on your own, change the names of the Entities you create.     Step 2: Create Mashup Widget Extension Project   First, let's get our tools installed and set. If you haven't created an extension before, see the Create An Extension guide on how to entirely configure your setup.   Download Eclipse ThingWorx SDK. Download Eclipse ThingWorx Plugin.   To create a new extensions project in the ThingWorx Extension Perspective, follow the steps below to get started:   Go to File->New->Project. Click ThingWorx->ThingWorx Extension Project.   Click Next. Enter the Project Name (for example, MyAwesomeExtension). Select Ant as your build framework. Gradle can be used if you are using a version of Eclipse that supports Gradle STS. Enter the SDK location by browsing to the directory where the Extension SDK zip is stored. Enter the Vendor information (for example, ThingWorx Labs). Change the default package version from 1.0.0 to support extension dependency. Click Next then click Finish. Your newly created project is added to the Package Explorer tab.   Creating Widgets   The ThingWorx Extensions SDK allows for easier development and in a shorter timeframe. The SDK provides steps for creating widgets, starting with an initial setup. Follow the steps below to get started on your own widget creation.   Choose the ThingWorx menu and select New Widget.   Select the parent project, in this case MyAwesomeExtension. Enter SimpleWidget for the name and A simple example of Widget creation. for description.   Click Finish.   A new folder under the /ui folder is created and contains the JavaScript and CSS files for the widget. The metadata.xml file under the configfiles directory is updated automatically. The generated JavaScript files contain a minimal implementation of the functions needed to produce a working widget.   Adding Third-Party JAR Files   There are scenarios in which a 3rd party JAR file might be required. None will be needed for this scenario, but take note of how to do it below.   Choose the Widget menu and select New Jar Resource. Select the parent project. Browse to and select the JAR file you want to add, and enter a description. Click Finish. The JAR file is added to the /lib folder and the metadata.xml file is updated automatically.   Adding Third-Party Resources and JavaScript Libraries   Third-party libraries, images, and other web artifacts needed for the widget should be placed in the /ui/<widgetname> folder or subfolders of that location. The *.ide.js and *.runtime.js files can then reference any of those artifacts via the relative path of: …/Common/extensions/<extensionname>/ui/<widgetname>/   For example, to include a third-party JavaScript library and CSS into your widget code, one would do the following: if (!jQuery().qtip) { $("body").append('<script type="text/javascript" src="../Common/extensions/MyAwesomeExtension/ui/SimpleWidget/include/qtip/jquery.qtip.js"></script>'); $("head").append('<link type="text/css" rel="stylesheet" href=" ../Common/extensions/MyAwesomeExtension/ui/SimpleWidget/include/qtip/jquery.qtip.css" />'); }     Step 3: Widget Lifecycle in the Mashup Builder   A widget has the following lifecycle stages within the Mashup Builder. During each lifecycle stage, the specified functions on the widget are called by the Mashup Builder.   Discovered   The widget is being loaded into index.html and added to the Widget toolbar/palette.   widgetProperties() - Called to get information about each widget (such as display name and description)   widgetEvents() - Called to get information about the events each widget exposes   widgetServices() - Called to get information about the services each widget exposes   Created   The widget is dragged onto a Mashup panel.   afterload() - Called after your object is loaded and properties have been restored from the file, but before your object has been rendered   Appended   The widget is appended to the workspace DOM element.   renderHtml() - Called to get an HTML fragment that will be inserted into the Mashup DOM element   afterRender() - Called after the HTML fragment representing the widget has been inserted into the Mashup DOM element and a usable element ID has been assigned to the DOM element holding the widget content. The DOM element is then ready to be manipulated.   Updated   The widget is resized or updated in the Widget property window.   beforeSetProperty() - Called before any property is updated   afterSetProperty() - Called after any property is updated   Destroyed   The widget is deleted from the mashup.   beforeDestroy() - Called right before the widget’s DOM element is removed and the widget is detached from its parent widget and deallocated. You should clean up resources (such as plugins and event handlers) acquired during the lifetime of the widget.     Step 4: Widget Coding Examples   The [widgetname].ide.js file must implement several functions to work correctly in the Mashup Builder using its API. Widgets can declare widget properties, services, and events in functions.   Mashup Builder Code   Below is sample code for a widget named SimpleWidget with a bindable string property named DisplayText. TW.IDE.Widgets.simplewidget = function () { this.widgetIconUrl = function() { return "../Common/extensions/MyAwesomeExtension/ui/simplewidget/SimpleWidget.ide.png"; }; this.widgetProperties = function () { return { name : "SimpleWidget", description : "A simple example of Widget creation.", category : ["Common"], properties : { DisplayText: { baseType: "STRING", defaultValue: "Hello, Awesome User!", isBindingTarget: true } } } }; this.renderHtml = function () { var mytext = this.getProperty('SimpleWidget Property'); var config = { text: mytext } var widgetTemplate = _.template( '<div class="widget-content widget-simplewidget">' + '<span class="DisplayText"><%- text %></span>' + '</div>' ); return widgetTemplate(config); }; this.afterSetProperty = function (name, value) { return true; }; };   Runtime Coding   To handle the widget at runtime, you need methods to do the following: Render the HTML at runtime Set up bindings after rendering the HTML Handle property updates Below is sample code of what the [widgetname].runtime.js may look like: TW.Runtime.Widgets.simplewidget = function () { var valueElem; this.renderHtml = function () { var mytext = this.getProperty('SimpleWidget Property'); var config = { text: mytext } var widgetTemplate = _.template( '<div class="widget-content widget-simplewidget">' + '<span class="DisplayText"><%- text %></span>' + '</div>' ); return widgetTemplate(config); }; this.afterRender = function () { valueElem = this.jqElement.find(".DisplayText"); valueElem.text(this.getProperty("DisplayText")); }; this.updateProperty = function (updatePropertyInfo) { if (updatePropertyInfo.TargetProperty === "DisplayText") { valueElem.text(updatePropertyInfo.SinglePropertyValue); this.setProperty("DisplayText", updatePropertyInfo.SinglePropertyValue); } }; };   Advanced Examples   If you have a local installation of the ThingWorx Composer, you can find examples of widgets in the Tomcat_Installation_Folder/webapps/Thingworx/Common/thingworx/widgets directory. DO NOT EDIT THESE FILES!. You will be able to mimic widgets you like to use them as a basis for new widgets. Or, just take notes on these items which will be covered more in-depth later in this guide.   Additional Features   You can incorporate the following features into your widgets: Services that can be bound to events (such as Click of a Button, Selected Rows Changed, or Service Completed) Events that can be bound to various services (for example, invoke a service and navigate to a mashup) Properties that can be bound out You can access the full power of JavaScript and HTML in your widget code at runtime. Anything that can be accomplished using HTML and JavaScript is available in your widget.     Click here to view Part 2 of this guide.  
View full tip
  Step 5: Add Property to Thing   Property values are associated with a specific Thing, and are used to store data that changes over time. Required Parameters   AppKey created by your ThingWorx server Name of the Thing to which the Property will be added Name for the new Property and data type of the Property's value   Request   Construct the URL. A new Property can be added to an existing Thing by making an HTTP POST to this endpoint. Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server that will have the Property added. <server_ip:port>/Thingworx/Things/<name of Thing>/Services/AddPropertyDefinition       2. Send request parameters. The name of the new Property to be added and type of the Property are sent in the body of the POST as a JSON object. For example, the JSON object below will create a new Property named SomeNumber using the ThingWorx base type NUMBER. Some other commonly used types are STRING, INTEGER, and BOOLEAN. { "name" : "SomeNumber", "type" : "NUMBER" }   NOTE: The full request must include a header with the appKey for your specific ThingWorx server.   Response   A successful call to the AddPropertyDefinitionservice does not return any content in the body of the response. Only an HTTP 200 is returned.   HTTPie example:   http -v -j http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/AddPropertyDefinition appKey==64b879ae-2455-4d8d-b840-5f5541a799ae name=SomeNumber type=NUMBER   WARNING for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The POST request to the AddPropertyDefinition endpoint has a JSON body so the header must be set to match the format of the request body.   The Content-Type header does not appear in the sample HTTPie call because HTTPie sets the Accept and Content-type request headers to application/json by default. Below is an example cURL call that explicitly sets the Content-Type header to application/json.   curl -v -H "Content-Type: application/json" -X POST -d '{"name": "SomeNumber","type": "NUMBER"}' http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/AddPropertyDefinition?appKey=d0a68eff-2cb4-4327-81ea-7e71e26b     Validate   View new Property on Server. The Property you just added is now available in the ThingWorx Composer. Before anything else can be done with your new Property through the REST API, the Thing must be restarted. To confirm your Property was added to your Thing, open Composer and click Things, select the name of the Thing you just created, then click Properties and Alerts. You will see the new Property listed. You may need to refresh to see the changes.             2. Execute RestartThing Service. Restart your Thing with the added Property by making a HTTP POST to the endpoint below. Substitute <name of Thing> with the actual name of the Thing you created. No body is required in the POST, however, the Content-Type header of a POST that executes a Service must always be set to application/json or text/xml even if the service does not take any parameters and no content is being sent. No body is returned upon success, only an HTTP 200 response code. <server_ip:port>/Thingworx/Things/<name of Thing>/Services/RestartThing   HTTPie example:   http -v -j POST http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/RestartThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae      Step 6: Set Property Value   You can set the value of a specific Property with the REST API using the PUT verb. Required Parameters:   AppKey created by your Foundation server A Name of valid Thing and name of Property New Property value   Request   Construct the URL. A Property value can be set by making an HTTP PUT call to this endpoint: <server_ip:port>/Thingworx/Things/<name of Thing>/Properties/<name of Property> Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server and <name of Property> with the name of a Property that has been added to the Thing.       2. Send request parameters.   The name of the Property to be set is duplicated in the body of the PUT and is sent along with the value as a JSON object. The example below will set the Property SomeNumber to 34.4 { "SomeNumber" : 34.4 } NOTE: The full request must include authentication credentials for your specific ThingWorx server.   Response   A successful call to set a Property does not return any content in the body of the response. Only an HTTP 200 is returned.   HTTPie example   http -v -j PUT http://52.201.57.6/Thingworx/Things/SomeTestThing/Properties/SomeNumber appKey==64b879ae-2455-4d8d-b840-5f5541a799ae SomeNumber=34.4   WARNING for other HTTP clients: By default HTTPie sets the Accept and Content-type request headers to application/json. A PUT request to the Properties endpoint has a JSON body so the Content-Type header must be set to match the format of the request body.   Most HTTP clients do not set the correct header by default and it must be set explicitly. Below is an example cURL call that sets the Content-Type header to application/json   curl -v -H "Content-Type: application/json" -X PUT -d '{"SomeNumber":12.34}' http://52.201.57.6/Thingworx/Things/SomeTestThing/Properties/SomeNumber?appKey=d0a68eff-2cb4-4327-81ea-7e71e26b     Validate   To confirm your Property was changed for your Thing, go to Composer and click Things. Select the name of the Thing you just created, then click Properties and Alerts tab. Click on the circular arrow Refresh to see the updated Property value.       Step 7: Get Latest Property Value   You can retrieve Property values of a specific Thing with the REST API using the GET verb.   Required Parameters:   AppKey created by your ThingWorx server Name of Thing and name of Property   Request   Construct the URL. To get the current value for a property, make a GET request to this endpoint: <server_ip:port>/Thingworx/Things/<name of Thing>/Properties/<name of property> Substitute <name of thing> with the actual name of a Thing that exists on the ThingWorx server and <name of Property> with the name of a Property that has been added to the Thing.   NOTE: The full request will also need to include the hostname and authentication credentials for your specific ThingWorx server.         2. Send request parameters. Other than authentication, no other parameters are used in  this GET request.   Response   The content can be returned in four different formats by sending an Accept header with the request.   Desired Response Type Accept Header Values JSON application/json XML text/xml HTML text/html (or omit Accept Header) CSV text/csv   HTTPie example:   http -v -j http://52.201.57.6/Thingworx/Things/SomeTestThing/Properties/SomeNumber appKey==64b879ae-2455-4d8d-b840-5f5541a799ae     Click here to view Part 3 of this guide.
View full tip
  Leverage the REST API to create Things, modify Properties, execute Services and more.   GUIDE CONCEPT   This project will introduce you to the REST API utilized by the ThingWorx platform.   Following the steps in this guide, you will be able to connect to the ThingWorx platform and make REST calls to call Services, update Properties, and perform a number of actions for your IoT applications.   We will teach you how to use the ThingWorx REST API to create a more robust application. With the REST API you can leverage the full power of the ThingWorx Foundation server with simple HTTP requests. The REST API can easily be explored using a command line tool such as curl, a browser plugin like Postman, or any preferred programming language.   YOU'LL LEARN HOW TO   Create new Things on a ThingWorx Foundation Server Add Properties to Things Access Property values Execute custom Services   NOTE: The estimated time to complete ALL 4  parts of this guide is 30 minutes.      Step 1: REST API Design   Almost every Entity and Service of ThingWorx can be accessed through the REST API. This step will review some points that are common to all ThingWorx REST API calls.   REST API Syntax   The endpoint URLs used by the REST API follow the consistent pattern shown in the diagram below.   The following table describes the individual pieces of the URL for the REST API calls.   Term Description Optional/Required? http method GET, PUT, DELETE, POST required scheme http, https required host server IP address where ThingWorx is running required port port on which the Web Server is listening for requests (default is 80) optional entity collection One of the built-in entity collection types proprietary to ThingWorx required entity name that identifies a specific characteristic required characteristic collection Names such as Property Definition, Properties VTQ, ThingName, and Service Definition optional characteristic name of the Service or Property on which to execute optional accept header format of HTTP content being requested; must be application/json or text/xml or text/html optional content type header format of HTTP content being provided; must be application/json, text/csv or text/html required content   optional query parameters   optional   Requests   The ThingWorx REST API uses HTTP request verbs in ways common to many REST APIs:   GET to retrieve information POST for both creating a new entity and executing a service DELETE to remove a Thing or Property PUT to change the value of an existing entity When a REST API request requires parameters to be sent, the Content-Type header must be set to match the format of the request body.   Discovering and using Services requires using a dedicated URL. To list available Services and see their definitions, issue a GET to   ``` <server_ip:port>/Thingworx/Things/<name of thing>/ServiceDefinitions ``` In order to execute a listed Service issue a POST to   ``` <server_ip:port>/Thingworx/Things/<name of thing>/Services/<service name> ```   NOTE: The Content-Type header of a POST that executes a Service must always be set to application/json or text/xmleven if the service does not take any parameters and no content is being sent.   Responses   The following tables describe the valid Accept and Content-Type header values when making a REST API calls.   Accept Headers   If the request sends either an invalid Accept header, or no Accept header is supplied, the default response will be in text/html format.   Value Syntax JSON application/json XML text/xml HTML text/html (or omit Accept header) CSV text/csv   Content Type Headers   A Content-Type header indicating the format of data sent to ThingWorx, is required. Some POST requests require a content type header even when no data is being sent.   Value Syntax JSON application/json XML text/xml     Step 2: REST Client   In order to make calls to any REST API you need a client software. A web browser can be used to make some GET calls, but you must install extensions to modify headers or to make POST or PUT calls.   Client software options include:   cURL is a venerable command line tool and library that is a Swiss Army Knife of dealing with web requests. And like an old Swiss Army Knife you can make it work but you might wind up hurting yourself.   Httpie is a modern command line tool with easy to use, intuitive options. Server responses are shown in color with easy to read formatting. The examples will be given as HTTPie commands.   NOTE: The following steps in this guide use Httpie as the client software.     Step 3: Create Application Key   In this Quickstart, you will use ThingWorx Composer to generate an Application Key. A device must be authenticated to send data to, or recieve data from ThingWorx. One of the most common authentication methods used with ThingWorx is by using a security token called an Application Key or appKey. These tokens are associated with a particular user and have the same permissions as that user.   Create an Application Key   On the Home screen of Composer click + New. In the dropdown list, click Applications Key.   Give your Application Key a name (ie, MyAppKey). Set the User Name Reference to a User you created. Update the Expiration Date field, otherwise it will default to 1 day. Click Save.   A Key ID has been generated and can be used to make secure connections.   BEST PRACTICE: We recommend you create separate keys for every connected device, User or system. This allows better security in case of situations where you may need to revoke access from one of them.     Step 4: Create New Thing   A Thing is a basic building block used to model applications in the ThingWorx Foundation Server. All Things are based on a Thing Template, either a built-in system template or a custom Template that was previously created. With the REST API, you can create, modify, list, and delete Things. After a Thing has been created by using an API call, it must be enabled and restarted with additional API calls before it can be used.   Required Parameters   AppKey created by your ThingWorx server A name for the new Thing The name of a valid ThingTemplate that will be used to create the new Thing Request   An HTTP POST request to ThingWorx is assembled from 3 components: a URL A POST body Authentication credentials A request to ThingWorx can be made only after these 3 components are properly configured.         1.  Construct the URL.   Create a new Thing by making an HTTP POST to the endpoint.   <server_ip:port>/Thingworx/Resources/EntityServices/Services/CreateThing NOTE: The server_ip is the ip address of your ThingWorx Core server.        2. Required POST body parameters.   Send the name of the Thing and the name of the ThingTemplate that will define the new thing in the body of the POST as a JSON object. For example, the JSON object below will create a new Thing named SomeTestThing using the system template GenericThing. { "name": "SomeTestThing", "thingTemplateName": "GenericThing" }   TIP: When creating Things that will be used with the REST API, use the GenericThing ThingTemplate or a ThingTemplate based GenericThing. A RemoteThing should only be used with devices that make an AlwaysOn™ connection to a ThingWorx server using the Edge MicroServer or one of the AlwaysOn™ SDKs.        3. Authenticate the Request.   All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter. .../CreateThing?appKey=64b87... , or as request header appKey: 64b87... Refer to Step 13: Authentication Tags for an overview of different authentication methods. Response   A successful call to the CreateThing service does not return any content in the body of the response, only an HTTP 200 is returned.   Examples HTTPie example:   http -v http://52.201.57.6/Thingworx/Resources/EntityServices/Services/CreateThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae name=SomeTestThing thingTemplateName=GenericThing   The Content-Type header does not appear in the sample HTTPie call because HTTPie sets the Accept and Content-type request headers to application/json by default.   WARNING for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The POST request to the CreateThing endpoint has a JSON body so the header must be set to match the format of the request body.   cURL example   curl -v -H "Content-Type: application/json" -X POST -d '{"name": "SomeTestThing","thingTemplateName": "GenericThing"}' http://52.201.57.6/Thingworx/Resources/EntityServices/Services/CreateThing?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645 Note: cURL explicitly sets the Content-Type header to application/json.     Validate   The Thing you just created is now available in the ThingWorx Composer, however before anything else can be done with your new Thing through the REST API it must be enabled and started. Follow these steps to validate that the new Thing has been created and enabled.   From the home page of Composer, click Things, select the name of the Thing you just created, then click General Information.   NOTE: You will see the Active checkbox is not checked indicating this Thing is not Enabled.       2. Execute EnableThing Service.   To enable your newly created Thing, make an HTTP POST to the endpoint below. Substitute <name of Thing> with the actual name of the Thing you created. No body is required in the POST, however, the Content-Type header of a POST that executes a Service must always be set to application/json or text/xml even if the service does not take any parameters and no content is being sent. No body is returned upon success, only an HTTP 200 response code. <server_ip:port>/Thingworx/Things/<name of Thing>/Services/EnableThing HTTPie example   http -v -j POST http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/EnableThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae         3.  Confirm new Thing is Enabled.   To update the General Information section of your new Thing and confirm the Active checkbox is now checked, refresh the page with the browser or close and re-open your Thing.         4. Restart your Thing.   After a Thing is created and whenever any changes are made to its structure, the Thing has to be restarted. Start you new Thing by making a HTTP POST to the endpoint below. Substitute <name of Thing> with the actual name of the Thing you created. No body is required in the POST, however, the Content-Type header of a POST that executes a Service must always be set to application/json or text/xml even if the service does not take any parameters and no content is being sent. No body is returned upon success, only an HTTP 200 response code. <server_ip:port>/Thingworx/Things/<name of Thing>/Services/RestartThing HTTPie example:   http -v -j POST http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/RestartThing appKey==64b879ae-2455-4d8d-b840-5f5541a799ae     Click here to view Part 2 of this guide
View full tip
  Step 5: Mashup Builder API   The following APIs can be accessed by a widget in the context of the Mashup Builder:    API                                                                                                                Description this.jqElementId This is the DOM element ID of your object after renderHtml(). this.jqElement This is the jquery element. this.getProperty(name) / this.setProperty(name,value) Note that every call to this function will call afterSetProperty() if it’s defined in the widget. this.updatedProperties() This function should be called anytime properties are changed in the widget so that the Mashup Builder can update the widget properties window, the connections window, and so on. this.getInfotableMetadataForProperty(propertyName) If you need the infotable metadata for a property that you bound, you can get it by calling this API; it returns undefined if it is not bound. this.resetPropertyToDefaultValue(propertyName) This call resets the named property to its default value. this.removeBindingsFromPropertyAsTarget(propertyName) This call removes target data bindings from the propertyName. Use it only when the user has initiated an action that invalidates the property. this.removeBindingsFromPropertyAsSource(propertyName) This call removes source data bindings from the propertyName. Use this only when the user has initiated an action that invalidates the property. this.isPropertyBoundAsTarget(propertyName) This call returns a result that indicates if the property has been bound as a target. You can use it to determine if a property has been set or bound. this.isPropertyBoundAsSource(propertyName) This call returns a result that indicates if the property has been bound as a source. You can use it to determine if a property has been bound to a target.   Example of the Checkbox Widget’s validate() function: this.validate = function () { var result = []; if (!this.isPropertyBoundAsSource('State') && !this.isPropertyBoundAsTarget('State')) { result.push({ severity: 'warning', message: 'State for {target-id} is not bound' }); } return result; }   Example of the Blog Widgets validate() function: this.validate = function () { var result = []; var blogNameConfigured = this.getProperty('Blog'); if (blogNameConfigured === '' || blogNameConfigured === undefined) { if (!this.isPropertyBoundAsTarget('Blog')) { result.push({ severity: 'warning', message: 'Blog is not bound for {target-id}' }); } } return result; }     Step 6: Mashup Builder Callbacks   The following widget functions are called by the Mashup Builder to control the widget’s behavior. widgetProperties() - Returns a JSON structure that defines the properties of the widget. Listed are the possible properties of the widget:   Required Property   The only required property is:   name - The user-friendly widget name, as shown in the widget toolbar   Optional Properties   There are a number of optional properties that can be contained in the returned JSON structure.    Property                                                                 Description description A description of the widget, used for its tooltip. iconImage - File name of the widget icon/image category An array of strings for specifying one or more categories to which the widget belongs (such as “Common”, “Charts”, “Data”, “Containers”, and “Components”), enabling widgets to be filtered by type/category. isResizable true (default) or false defaultBindingTargetProperty Name of the property to use as the data/event binding target borderWidth If the widget has a border, set this property to the width of the border. This property ensures pixel-perfect WYSIWG between design and runtime. If you set a border of one pixel on the widget-content element at design time, you are making the widget two pixels taller and two pixels wider (one pixel on each side). To account for this discrepancy, set the borderWidth property to make the design-time widget the same number of pixels smaller. This property places the border inside the widget that you created and makes the width and height in the widget properties accurate. isContainer true or false (default). Controls whether an instance of the widget can be a container for other widget instances. customEditor The name of the custom editor dialog for entering and editing the widget configuration. The system assumes there is a dialog you created named TW.IDE.Dialogs.<name>. customEditorMenuText The text that appears on the flyout menu of the widget and the tooltip text for the Configure Widget Properties button. For example, “Configure Grid Columns.” allowPositioning true (default) or false supportsLabel true or false (default). If true, the widget exposes a label property used to create a text label that appears next to the widget in the Composer and at runtime. supportsAutoResize true or false (default). If true, the widget can be placed in responsive containers (such as columns, rows, responsive tabs, responsive mashups). properties A collection of JSON objects for the widget that describe the properties of the widget that can be modified when the widget is added to a mashup. These properties are displayed in the Properties window of the Mashup Builder - the name of each object is used as the property name and the corresponding attributes control how the property value is set. afterLoad() Called after the object is loaded and properties have been restored from the file, but before the object has been rendered renderHtml() [required] Returns HTML fragment that the Composer will place in the screen; the widget’s content container (e.g. div) must have a ‘widget-content’ class specified. After this container element is appended to the DOM, it becomes accessible via jqElement and its DOM element ID will be available in jqElementId widgetEvents() A collection of events. warnIfNotBound true or false; If true, the property will be checked by Composer to determine whether it is bound, then generate a to-do item if/when it is not. widgetServices() A collection of services. warnIfNotBound true or false; If true, the property will be checked by the Composer to determine whether it is bound, then generate a to-do item if/when it is not. afterRender() Called after the HTML fragment is inserted into the DOM. beforeDestroy() Called right before the widget’s DOM element gets removed and the widget is detached from its parent widget and delocated; this is the place in which to perform any clean-up of resources (e.g. plugins, event handlers) acquired throughout the lifetime of the widget. beforeSetProperty(name,value) [Mashup Builder only - not at runtime] Called before any property is updated within Composer; this is a good place to perform validation on the new property value before it is committed. If a message string is returned, then the message will be displayed to the user, and the new property value will not be committed. If nothing is returned, then the value is assumed to be valid. afterSetProperty(name,value) [Mashup Builder only - not at runtime] Called after any property is updated within Composer. Return true to have the widget re-rendered in Composer. afterAddBindingSource(bindingInfo) Whenever data is bound to the widget, you will call back with this (if you implemented it … it’s optional). The only field in bindingInfo is targetProperty which is the propertyName that was just bound. validate() Called when Composer refreshes its to-do list. The call must return an array of result objects with severity (optional and not implemented) and message (required) properties. The message text may contain one or more pre-defined tokens, such as {target-id}, which will contain a hyperlink that allows the user to navigate to or select the specific widget that generated the message.   Properties Section Breakdown   The following attributes can be specified for each property object:    Aspect                                           Description description A description of the widget, which is used for its tooltip. baseType The system base type name - if the baseType value is FIELDNAME the widget property window displays a dropdown list of fields available in the INFOTABLE bound to the sourcePropertyName value based on the baseTypeRestriction. mustImplement If the baseType is THINGNAME and you specify “mustImplement”, the Mashup Builder will restrict popups to those implementing the specified EntityType and EntityName [by calling QueryImplementingThings against said EntityType and EntityName]. baseTypeInfotableProperty If baseType is RENDERERWITHFORMAT, baseTypeInfotableProperty specifies which property’s infotable is used for configuration. sourcePropertyName When the property’s baseType is FIELDNAME, this attribute is used to determine which INFOTABLE’s fields are to be used to populate the FIELDNAME dropdown list. baseTypeRestriction When specified, this value is used to restrict the fields available in the FIELDNAME dropdown list. tagType If the baseType is TAGS this can be ‘DataTags’ (default) or ‘ModelTags.’ defaultValue Default undefined; used only for ‘property’ type. isBindingSource true or false; Allows the property to be a data binding source, default to false. isBindingTarget true or false; Allows the property to be a data binding target, default to false. isEditable true or false; Controls whether the property can be edited in Composer, default to true. isVisible true or false; Controls whether the property is visible in the properties window, default to true. isLocalizable true or false; Only important if baseType is STRING - controls whether the property can be localized or not. selectOptions An array of value / (display) text structures. warnIfNotBoundAsSource true or false; If true, the property will be checked by Composer to determine whether it is bound and generate a to-do item if/when it is not. warnIfNotBoundAsTarget true or false; If true, the property will be checked by Composer to determine whether it is bound and generate a to-do item if/when it is not.   Other Special BaseType   Additional special baseTypes:   STATEDEFINITION - Picks a StateDefinition STYLEDEFINITION - Picks a StyleDefinition RENDERERWITHSTATE - Displays a dialog and allows you to select a renderer and formatting. Note: You can set a default style by entering the string with the default style name in the defaultValue. When your binding changes, you should reset it to the default value, as shown in the code below:   this.afterAddBindingSource = function (bindingInfo) { if(bindingInfo['targetProperty'] === 'Data') { this.resetPropertyToDefaultValue('ValueFormat'); } }; STATEFORMATTING - Displays a dialog and allows you to pick a fixed style or state-based style. Note: You can set a default style by entering the string with the default style name in the defaultValue. When your binding changes, you should reset it to the default value as shown in the code above for RENDERERWITHSTATE. VOCABULARYNAME - Will pick a DataTag vocabulary   Some Examples   An example of the properties property: properties: { Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, }   An example of mustImplement: 'baseType': 'THINGNAME', 'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' }   An example of selectOptions:[ {value: ‘optionValue1’, text: ‘optionText1’}, {value: ‘optionValue2’, text: ‘optionText2’} ]   An example of validate function that allows you to navigate/select the specific widget that generated the message: this.validate = function () { var result = []; var srcUrl = this.getProperty('SourceURL'); if (srcUrl === '' || srcUrl === undefined) { result.push({ severity: 'warning', message: 'SourceURL is not defined for {target-id}'}); } return result; }     Click here to view Part 3 of this guide.
View full tip
  Step 8: Call Custom Service   In order to execute a Service of a specific Thing with the REST API, you can use the POST verb.   Required Parameters:   AppKey created by your ThingWorx server Name of the Thing that implements a custom Service Name of the custom Service Names of inputs, if any, required by the Service Request   Construct the URL. To call a custom Service of an existing Thing, make an HTTP POST to this endpoint: <server_ip:port>/Thingworx/Things/<name of Thing>/Services/<name of Service> Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server, and <name of Service> with an existing Service. Send request parameters The names of the inputs along with their values are sent in the body of the POST as a JSON object. For example, the JSON object below will send a parameter named 'firstNumber' with a value of 35 and a parameter named secondNumber with a value of 711. { "firstNumber": "35", "secondNumber": "711" } NOTE: The full request must include a header with the appKey for your specific ThingWorx server.   Response   A successful call to a Service will return a JSON object in the body of the response containing both a DataShape object and an array named rows. Inside the array, an object named result will have the value returned by the custom Service. Here is an example response:   { "dataShape": { "fieldDefinitions": { "result": { "aspects": {}, "baseType": "NUMBER", "description": "", "name": "result", "ordinal": 0 } } }, "rows": [ { "result": 746.0 } ] } WARNING for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The POST request to the Service endpoint has a JSON body so the header must be set to match the format of the request body.   Step 9: Import and Export Entities   Collections of Entities that perform a function can be grouped then shared by exporting from a server. These entity collections are called Extensions and can be uploaded using the REST API. You can create custom Extensions or download Extensions created by other developers. You can use the REST API to automate the process of uploading an Extension to a ThingWorx server.   Required Parameters   AppKey created by your Foundation server Path to properly formatted zip file containing extension Entities Request   Construct the URL. Upload an Extension by making an HTTP POST to the endpoint: <Server IP:port〉Thingworx/ExtensionPackageUploader Send request parameters. The zip file that contains the extension entities is uploaded as a multi-part POST. The name of the file parameter is upload. Use a library to properly format the multi-part POST request You must also send this header: X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE Authenticate the Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...   Response   A successful call to upload an Extension will return a description of the Entities that were successfully uploaded in the body of the response.   HTTPie example: http -f POST iotboston.com:8887/Thingworx/ExtensionPackageUploader upload@/home/ec2-user/extension.zip X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE appKey:d0a68eff-2cb4-4327-81ea-7e71e26bb645 cURL example: curl -v --header X-XSRF-TOKEN:TWX-XSRF-TOKEN-VALUE --header appKey:d0a68eff-2cb4-4327-81ea-7e71e26bb645 -F upload=@extension.zip iotboston.com:8887/Thingworx/ExtensionPackageUploader?purpose=import&validate=false     Download Things By Name   The REST API can be used to export a file representation of Things on a ThingWorx Foundation server. The downloaded file can be imported to another ThingWorx server making the Thing available for use.   Required Parameters   AppKey created by your Foundation server Name of the Thing Request   Construct the URL. Retrieve the components of a Thing by making an HTTP GET to the endpoint. Substitute <name of Thing> with the actual name of a Thing that exists on the ThingWorx server that wil be downloaded. <Server IP:port>/Thingworx/Exporter/Things/<name of Thing> Send request parameters. No parameters are sent. Authenticate the Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...   Response   It is possible for the content to be returned in two different formats by sending an Accept header with the request.   Desired Response Type  Accept Header Values JSON application/json XML text/xml HTML text/html (or omit Accept Header) CSV text/csv   A successful call to download a Thing will return a file in the body of the response suitable for importing into a ThingWorx Foundation server.   HTTPie example:   http -v GET iotboston.com:8081/Thingworx/Exporter/Things/PiThing appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645 Accept:text/xml     Download Things By Tag   The REST API can be used to export a file representation of Things on a ThingWorx Foundation server. This file can be imported to another ThingWorx server making the Thing available for use.   Required Parameters   AppKey created by your Foundation server Name of the Tag Request   Construct the URL. Retrieve the components of a Thing by making an HTTP GET to the endpoint <Server IP:port〉/Thingworx/Exporter/Things Send request parameters. The Tag name is sent as a request parameter named: searchTags Authenticate the Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...   Response   It is possible for the content to be returned in two different formats by sending an Accept header with the request.   Desired Response Type  Accept Header Values JSON application/json XML text/xml HTML text/html (or omit Accept Header) CSV text/csv   A successful call to download a Thing will return a file in the body of the response suitable for importing into a ThingWorx Foundation server   HTTPie example:   http -v GET iotboston.com:8081/Thingworx/Exporter/Things searchTags==Applications:Raspberry_light appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645 Accept:text/xml     Step 10: Authentication Tags   A Tag is composed of two parts: a Vocabulary, and a specific vocabulary term. A Tag is shown as Vocabulary:VocabularyTerm. Almost every ThingWorx entity can be tagged. Tags can be used to create a relationship between many different ThingWorx Entities.   Create New Tag   You can use the REST API to create a new dynamic Tag vocabulary.   Required Parameters   AppKey created by your Foundation server Name of Tag Vocabulary   Request   Construct the URL. Create a new Tag Vocabulary by making an HTTP PUT to this endpoint: 〈Server IP:port〉/Thingworx/ModelTags Send Request Parameters. The name of the new DataShape and the name of the base DataShape that the new DataShape extends are sent in the body of the POST as a JSON object. For example, the JSON object below will create a new DataShape named SomeTestDataShape using the system template GenericThing. { "name": "SecondTest", "isDynamic": "true" } Authenticate Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...   Response   A successful call to the ModelTag Service does not return any content in the body of the response, only an HTTP 200 is returned.   HTTPie example:   http -v -j PUT http://52.201.57.6/Thingworx/ModelTags name=SecondTest isDynamic=true appKey==64b879ae-2455-4d8d-b840-5f5541a799ae     Warning for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The PUT request to the ModelTags endpoint has a JSON body so the header must be set to match the format of the request body. The Content-Type header does not appear in the sample HTTPie call because HTTPie sets the Accept and Content-type request headers to application/json by default. Below is an example cURL call that explicitly sets the Content-Type header to application/json.   curl -v -H "Content-Type: application/json" -X PUT -d '{"name": "SecondTest", "isDynamic":"true"}' http://52.201.57.6/Thingworx/ModelTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645   Add Tag to Thing   You can use the REST API to add a Tag to a Thing. There must be a Thing and a Dynamic Tag Vocabulary already created on your Foundation Server before you can add a Tag.   Required Parameters   AppKey created by your Foundation server Name of the Thing to be tagged Name of Dynamic Tag Vocabulary Name of for Tag to be assigned to Thing Request   Construct the URL. Substitute 〈name of Thing〉 with the actual name of a Thing that exists on the ThingWorx server that will have the Tag added. Add a new Tag to an existing Thing by making an HTTP POST to this endpoint: 〈Server IP:port〉/Thingworx/Things/〈name of Thing〉/Services/AddTags Send request parameters. The name of the new field to be added and type of the field are sent in the body of the POST as a JSON object. For example, the JSON object below will create a new field named SomeNumber using the ThingWorx base type NUMBER. Some other commonly used types are STRING, INTEGER, and BOOLEAN. Include a header in the full request with the appKey for your specific ThingWorx server. { "tags" : "SecondlightTest:RaspberryTest", }   Response   A successful call to the AddTags Service does not return any content in the body of the response. Only an HTTP 200 is returned.   HTTPie example:   http -v -j http://52.201.57.6/Thingworx/Things/SomeTestThing/Services/AddTags appKey==64b879ae-2455-4d8d-b840-5f5541a799ae tags=SecondTest:RaspberryTest curl -v -H "Content-Type: application/json" -X POST -d '{"tags": "SecondlightTest:RaspberryTest"}' http://52.201.57.6/Thingworx/Things/PiThing/Services/AddTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645 Warning for other HTTP clients: Most HTTP clients do not set a Content-Type header by default, without this header set the server will return an error message. The POST request to the AddPropertyDefinition endpoint has a JSON body so the header must be set to match the format of the request body. The Content-Type header does not appear in the sample HTTPie call because HTTPie sets the Accept and Content-type request headers to application/json by default. Below is an example cURL call that explicitly sets the Content-Type header to application/json.   curl -v -H "Content-Type: application/json" -X POST -d '{"tags": "SecondlightTest:RaspberryTest"}' http://52.201.57.6/Thingworx/Things/PiThing/Services/AddTags?appKey=d0a68eff-2cb4-4327-81ea-7e71e26bb645      Click here to view Part 4 of this guide.  
View full tip
  Learn how to send and receive JSON and XML payloads to SOAP and REST services.   GUIDE CONCEPT   This project will introduce how to create services that can send and receive XML and JSON payloads.   Following the steps in this guide, you will develop services to handle, send, and receive XML and JSON.   We will teach you how to use the ThingWorx Platform to handle REST requests and send payload for external SOAP and REST services.   YOU'LL LEARN HOW TO   Efficiently handle, send, and receive XML and JSON in ThingWorx Make requests to external REST services Make requests to external SOAP services   NOTE:  The estimated time to complete all parts of this guide is 60 minutes.     Step 1: Completed Example   Download the attached JSONXMLEntities.zip from attached files and import it into ThingWorx Composer.   In this tutorial, you will learn how to make and handle requests to live external REST and SOAP services. The entities file provided contains the following files and entities as a completed version of the scenario that will be covered:   Name Description JSONRequestThing Thing with examples of making requests using JSON XMLRequestThing Thing with examples of making requests using XML JSONHandlerThing Thing with examples of handling JSON requests and returning organized data XMLHandlerThing Thing with examples of handling XML requests and returning organized data This guide will use services provided by Microsoft Azure. Create a free account to utilize Microsoft Azure Web API services. In order to utilize this web api, obtain a FREE API key from Microsoft Azure Portal using these Microsoft Azure instructions. You are able to use other Web APIs for this guide.   Follow the next steps in order to get started.     Step 2: Sending JSON Based Requests   Whether making a request to a public web service or sending data to a device running an application, ThingWorx is able to utilize different REST request methods (GET, POST, PUT, DELETE, etc) using the ContentLoaderFunctions Resource. This same resource provides services for XML payloads, but JSON is the default formatting for REST. See the "Sending XML Based Requests" section in this guide for working with XML. This guide will not explain REST or REST methods, only how to use these REST methods.   To get started, create a Thing using the below steps. You will create new services in this Thing to make REST requests and add a service to help with HTML encoding. NOTE: Examples of these services can be found in the JSONRequestThing entity, which is provided in the download. In ThingWorx Composer, click the + New at the top of the screen. Select Thing in the dropdown. Name the Thing JSONRequestExample and set the Base Thing Template to GenericThing. Click Save. Click the Services tab. Create a new service called EncodeQueryToHTML. Add the following Input: Name Base Type Required query String True   8. Add the following JavaScript to help encode the string and return an HTML friendly string. try { var result = ""; if(query) { result = query.replace(/&/g, "&").replace(/>/g, ">").replace(/</g, "<").replace(/"/g, "'"); } } catch(error) { logger.error("JSONRequestThing.EncodeQueryToHTML(): Error Encoding String - " + error.message); }   9. Click Save and Continue to save your changes.   GET Requests   For GET requests to a REST service, you will use the GetJSON service of the ContentLoaderFunctions Resource. This service takes parameters from the proxy information to how to handle SSL issues. All of the parameters are optional. Perform the following steps to create your ThingWorx service to make REST Get requests.   In the Services tab of the JSONRequestExample Thing, create a new service called JSONGetRequest. The service will have the below properties as Input. Name Base type Required url String True header JSON False   3. In the Snippets section, filter and search for GetJSON. 4. Once you've found GetJSON under the ContentLoaderFunctions section, add it to the editor. You'll see all of the possible parameters for the request. In this example, we'll only set the url and header values. 5. Update the code snippet to include the parameters. Use the below code as a reference. var params = { headers: header /* JSON */, url: url /* STRING */ }; // result: JSON var result = Resources["ContentLoaderFunctions"].GetJSON(params);   6. Set the Output as JSON. 7. Click Save and Continue to save your changes. This code will enable REST requests to be sent to an available web service. You will need to include the query string in the URL. In the provided sample, open the JSONRequestThing Thing and check out the JavaScript for the SearchMicrosoftBing service for a more complex example. Note that you are setting the subscription key needed for a Microsoft Azure request and how to encode raw string input into a query string. Check out the Microsoft Azure documentation of the varying query strings that can be used.     POST/PUT Requests POST and PUT requests are created similarly to GET requests. The methods in the ContentLoaderFunctions Resource is PostJSON and PutJSON. These services include a JSON based paramter titled content. This parameter will allow you to compose the body of the request.   Based on how the REST service is implemented, data will be in the content parameter or the headers parameter. See below for steps on creating a POST request. In the Services tab of the JSONRequestExample Thing, create a new service called JSONPostRequest. The service will have the below properties as parameters. Name Base Type Required url String True header JSON False body JSON False   3. In the Snippets section, filter and search for PostJSON. 4. Once you've found PostJSON under the ContentLoaderFunctions section, add it to the editor. 5. Update the parameter object to use the parameters for the service. Keep in mind, there are different ways this can be done. If the URL or the header will always be the same, then save these values as properties on the Thing and add parameters if the URL for this request will need them. 6. Test the new service with a running REST application or use both the GET and POST methods to setup your Azure Active Directory.   DELETE Requests   In ThingWorx, the DELETE method will be called similarly to the GET method. There will be a number of parameters that can be used and you will need to call the DELETE service of the ContentLoaderFunctions Resource. Follow to below instructions.   Duplicate the JSONGetRequest service you created earlier in order to get a head start on the new service. When prompted, title this new service JSONDeleteRequest and save. In the code area, use the snippet once again to add the delete service from ContentLoaderFunctions. Update the JavaScript code to utilize the delete service. Save, and you're done!   A simple test for calling this delete method via Azure, is using the REST service to delete an email template. The URI and parameters can be found in the Azure API.     Click here to view Part 2 of this guide.
View full tip
  Dev Ops is a crucial process that exists in any software setting, whether you plan on it or not. Chaos in the dev ops process, say because less time is spent here than on the shiny new features that are easy to sell, results in bottlenecks in the dev ops process. Bottlenecks reduce efficiency, and leave you open to vulnerabilities as well. The faster you can get a change properly tested and safely into production, the safer and more stable the system is all along.   Issues will arise, they always arise. Are you ready for them? Watch this video, see some of these additional links, and think about your dev ops process now, before the fires start!   Useful Links:  ThingWorx Monitoring and Alerting Using Prometheus and Grafana, Part 1 ThingWorx Monitoring and Alerting Using Prometheus and Grafana, Part 2 Overview of Monitoring Tools and Diagnostics The System Health Timer
View full tip
    Hi, everyone!   In previous tech tips, I’ve introduced the ThingWorx 9.0 active-active clustering feature and provided architectural details and configurations. If you haven’t already, I recommend you check them out to learn more about how active-active clustering enables higher availability for ThingWorx: 9.0 Sneak Peek: Active-Active Clustering for ThingWorx 9.0 Sneak Peek: ThingWorx Architecture for Active-Active Clustering 9.0 Sneak Peek: Flexible Deployments of Active-Active Clustering for ThingWorx “ThingWorx on Air” Ep. 08: FAQs: ThingWorx Active-Active Clustering for Higher Availability   Today, I’ll provide more details around the load balancer in the active-active clustering architecture, some of its requirements, and a few configuration examples. Ready? Here we go! Here are the top four FAQs around the load balancer that will help you maximize your use of active-active clustering.   What do you mean by load balancing? Load balancing is the process of distributing network traffic across multiple servers. An algorithm employed by the load balancer or a proxy, determines how the traffic is distrusted. Round robin, fastest response, and least established connections are some of the most common methods of load balancing and provide different benefits, but all fundamentally ensure no single server bears too much demand. By spreading the traffic, load balancing improves application responsiveness. It also increases availability of applications and websites for users. Modern applications cannot run without load balancers. In general load balancers can run as hardware appliances or as software-defined. Hardware appliances often run proprietary software optimized to run on custom processors. As traffic increases, the vendor simply adds more load balancing appliances to handle the volume. Software defined load balancers usually run on less-expensive, standard Intel x86 hardware. Installing the software in cloud environments like Azure VMs or AWS EC2 eliminates the need for a physical appliance.   Following the seven-layer Open System Interconnection (OSI) model, load balancing occurs between layers four to seven (L4-Transport, L5-Session, L6-Presentation and L7-Application), whereas network firewalls are at levels one to three (L1-Physical Wiring, L2-Data Link and L3-Network). Load balancers have a various capabilities, which include: L4 — directs traffic based on data from network and transport layer protocols, such as IP address and TCP port. L7 — adds content switching to load balancing. This allows routing decisions based on attributes like HTTP header, uniform resource identifier, SSL session ID and HTML form data. GSLB — Global Server Load Balancing extends L4 and L7 capabilities to servers in different geographic locations. More enterprises are seeking to deploy cloud-native applications in data centers and public clouds. This is leading to significant changes in the capability of load balancers. What is a load balancer’s role in the ThingWorx Active-Active Clustering setup? As is true of any load balancer, the load balancer required in the ThingWorx Foundation active-active clustering architecture is responsible for distributing incoming traffic across the nodes within the cluster.   In the Active-Active Clustering architecture for ThingWorx, the load balancer distributes the traffic using a round-robin method. Please note that there are a several algorithms that provide load balancing techniques and this article is a good read for further understanding of it. A round-robin method rotates servers by directing traffic to the first available server and then moves that server to the bottom of the queue.   In ThingWorx clustering setup, while both WebSocket and HTTP incoming traffic are handled in a round-robin manner, they are routed differently by the load balancer.   HTTP traffic is directly distributed amongst the ThingWorx Foundation Servers within the cluster. Sticky sessions are used for the HTTP sessions—sticky via cookie, so individual users are tied directly to a single server node and see all of their changes instantaneously.   WebSocket traffic is distributed across the and is balanced via source IP to ensure each request from a device goes through the same connection server. From the ThingWorx Connection Server, the device traffic is distributed amongst the underlying ThingWorx Foundation Servers, not requiring another load balancer between the ThingWorx Connection Servers and ThingWorx Foundation Servers.   Please note that the WebSocket traffic load does not necessarily get distributed evenly nor do the incoming requests due to stickiness. For example: 2 users connect HTTP, one sends 100 requests and the other sends 2. Since they are sticky, it is not distributed evenly. 2 devices connect to a ThingWorx Connection Server. 1 is a gateway for 100 other devices, all requests fthe gateway go to the same connection server. The Connection Server does a round-robin to the underlying Foundation Servers so that the load would be better distributed across, but the load balancer is sticky to a ThingWorx Connection Server.     Which load balancer can I choose for setting ThingWorx in an Active-Active Cluster mode? ThingWorx active-active clustering is pretty much load balancer agnostic, meaning if the load balancer of your choosing that you might be using in your IT center meets the requirements, it can be utilized within the active-active clustering architecture. The load balancer is required to support the following features: Based on Layer-7 architecture Supports HTTP and WebSocket traffic Ability to support sticky sessions for  traffic and/or IP based stickiness. IP based means all traffic from a specific IP will be routed to the same server (this can be a problem with gateway type scenarios). Sticky sessions are based on a cookie, sessions are routed to same server based on cookie. Different users same IP could route to different machines. Health checking on server endpoints. (optional) It can manage SSL termination and SSL internal endpoints. Supports Path based routing. This is the ability to route to specific backends based on the URL or part of the URL. By default, all routes should go to the platform servers, but the following routes should go to the connection server: /Thingworx/WS /Thingworx/WSTunnelServer /Thingworx/WSTunnelClient /Thingworx/VWS All servers should be setup to only be part of load balancing based on their health configuration.  When configuring health check frequency, they should be run at a rate based on the tolerance for bad requests to be processed. Thingworx Foundation has a /health and /ready endpoint.   The /Thingworx/ready endpoint should be used for the load balancer.  It will return a 200 when the server is ready to receive traffic.  Connection Server checks health requests on a specific port and will return 200 when healthy. What are some of the compatible load balancers that I can use? While you can use any load balancer that satisfies the above request and meets your IT standards, below are some of the third-party load balancers that provide the features that are required of the active-active clustering architecture: HAProxy - HAProxy is a free, open source software that provides a high availability load balancer and proxy server for TCP and HTTP-based applications that spreads requests across multiple servers. It is very powerful and supports monitoring capabilities out of the box. PTC tests the clustering architecture using HA Proxy and provides a reference document for the same through the ThingWorx Foundation help center docs. Please note that it runs only on Linux environments. For a quick reference example of how to set up an HAProxy load balancer, see our Help Center here. NGINX - NGINX is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy serve. NGINX provides proxy capabilities as well as web server options. Some features like sticky sessions, advanced monitoring are not available in the opensource version and require you upgrade to NGINX Plus.  If you’re a Windows shop or already use NGINX Plus in your IT, then you may choose this load balancer offering.  However, please note that PTC doesn’t provide any official configuration steps of setting it up through our Help Center documentation. For a quick reference example of how to set up an NGNIX load balancer, see our Help Center here. AWS Application Load Balancer - Application Load Balancer (ALB) is best suited for load balancing of HTTP and HTTPS traffic and provides advanced request routing targeted at the underlying ThingWorx applications. Operating at the individual request level (Layer 7), Application Load Balancer routes traffic to targets within Amazon Virtual Private Cloud (Amazon VPC) based on the content of the request. If you’re running ThingWorx deployments on AWS, then you may choose to use AWS-offered managed load balancing services. F5: F5 Networks through its BIG-IP Local Traffic Manager solution provides advance load balancing techniques such as a full proxy where you can inspect, manage, and report on application traffic entering and exiting your network with additional features around SSL and performance optimization. Load balancers are another area where ThingWorx allows for flexibility and extensibility by enabling you to use the load balancer of your choosing that you’re most comfortable with or that best suits your needs (provided it meets the criteria above). You can also configure SSL or TLS for HAProxy when using ThingWorx HA clustering for end-to-end security. I hope this tech tip helped you develop a deeper understanding of how active-active clustering leverages load balancers to further increase your performance and thus availability and machine uptime, among many others.   If you’re not already on 9.0 and using active-active clustering, be sure to upgrade!   Stay connected, Kaya  
View full tip
Architecting Reason Code Trees in DPM Tori Firewind, IoT EDC   What are Machine Codes? Factory hardware devices communicate status changes to their human operators and other machines (IoT) via machine codes. The manufacturers often determine the machine codes for different types of factory hardware, so those are often pre-determined. However, how the reason trees map these machine codes to corresponding business logic in ThingWorx is entirely customizable. Knowing the best way to design your reason trees for this purpose can be challenging, so this guide is here to help with your conceptual knowledge. Using the UI to create, edit, and configure reason codes in technical detail can be found in the Help Center.    The Tree Trunk At the highest level of the reason tree, the trunk, there are really 3 categories: Availability (A), Performance or Productivity (P), and Quality (Q). These should look familiar; they are the three dimensions of OEE (Overall Equipment Effectiveness). Fg 1. Calculation of OEE Availability refers to long stops, events that stop planned production long enough that it makes sense to track a reason for being down (typically several minutes, but the threshold between a long stop and a short stop can vary depending on the ideal rate of production of materials).                  Availability = Run Time / Planned Production Time   Productivity/Performance really refers to short stops, things that cause the machine to run at less-than- optimal speeds. This can include stops caused by running out of materials for production, doing minor maintenance like switching out a single, easily-changed part, or even frequent breaks due to ill health of an operator. User error can be a cause as well, say if the machine needs a certain heat to produce parts, and the heat keeps fluctuating (requiring the machine to take the time to calibrate for this before starting on production) because operators are smoking out a back door or adjusting thermostat temperatures. Fg 2. Levels of Runnable Time   Operator influence often is a factor when it comes to the conditions that permit optimal performance from machinery, and every factory may face different challenges. Stops like these are not really outages; the amount of downtime isn’t enough to consider the production block entirely unproductive. Production was continuing and ongoing throughout most of the block despite the issues; the rate was just slower than ideal.                  Performance/Productivity = (Total Count / Run Time) / Ideal Run Rate   Quality refers mostly to the number of items that are considered scrap or rework, and it can be split into two categories: start up scrap (that which is expected because the machine is in the process of warming up or being fine-tuned by the operator) and production scrap (things which come out wrong and must be tossed or reworked because the conditions under which they were produced weren’t ideal; this is called first-pass yield only, meaning it's only a "good" product if it passes inspection the first time).                  Quality = Good Count / Total Count​   The Branches and the Leaves of the Tree The “leaves” are the reason codes which directly map to machine codes , and the “branches” are the method of categorization that connects them to the trunk. Both the leaves and the trees, the children and the parent nodes of the tree, are split into two states: planned versus unplanned downtime. Changeovers, maintenance, and even scrap, can be broken down into this dichotomy.   For scrap, there are startup rejects (planned, because the machines have ramp up periods) and production rejects (unplanned, because the conditions weren’t ideal). For maintenance there is planned and unplanned, small changes that occur on the fly that result in productivity loss, and maybe also reduce availability in the long run. Small, unplanned changes can occasionally shift into the availability loss category if a simple, quick repair winds up being complex and time-consuming. A good reason tree can differentiate easily between short and longer stops in order to respond to each in a deliberate way.   To start off in the process of architecting your reason tree, try writing the three categories on a board in a common room in an average factory (or several as a survey). Ask operators to stop in over the course of a few days and write various machine codes that they see often and find useful under one of these categories, or more than one if the machine code pops up under different circumstances and can mean different things. Have them write a 10 word justification, if the association isn’t obvious. Gather all of the “leaves” in this way, and then begin to associate them with the “trunk”, forming the “branches”.   An example tree can be seen in figure 3 here, with leaves like “Changeover” and “Maintenance” being semi-ambiguous; they could just as easily be seen as unplanned stops. Therefore, there may be multiple reason codes mapping up to the top of the tree in more than one branch, and these can have different categories, which controls how the business logic responds to the different codes. The Help Center has more details about how the events are mapped to types, and each type contains multiple categories, as configured by you when you set-up the DPM model. Fg 3: Different types of changeovers may have different codes, and can map up as either planned or unplanned, but all planned and unplanned stops (long stops) are under the Availability category of the trunk. Similarly, small stops can involve idling, like if there are not enough materials, reduced speed if the conditions are not ideal, or other small stops, usually caused by human error or unforeseeable circumstances. Quality loss then refers to the products which fail quality checks, either because the machine still has the wrong paint in the applicator and needs a few rounds to be ready for the next production item, or because the conditions are again, not ideal, and items wind up scrapped.   Example Reason Tree Fg 5 example tree with more specific tags (there may be dozens or hundreds in a full reason tree, though the fewer are needed to capture the events we care about, the better).   Theory of Constraints Fg 6 theory of constraint wheel: an industry process for gradual OEE improvement in factories that has been adapted into the PTC methodology as well. While architecting your reason tree, always remember the key purpose: gathering only as much data as necessary to analyze the efficiency of a factory and to identify the bottleneck, or the most limiting factor. The important point is to identify not just the bottleneck that seems the most troublesome, but the one that actually results in the greatest impact to OEE across the entire factory.   Without software like DPM, and a properly designed reason code tree, the process of improving a factory can be very challenging, involving a lot of guesswork, and sometimes solving one problem at the cost of another. The issue is that these machines produce a LOT of raw data, and humans are not the best tool available to gather and aggregate this data in a consumable way. A good reason tree ensures a smart application that can quickly prioritize the machine (bottleneck) that most impacts production, and not just the machine that functions in the least optimal way.   So, the theory of constraints is really a process for identifying small, incremental changes, which together can make a big difference, and fast, in factory OEE. The rate at which this cycle can be completed varies, however. The slower the process of identifying constraints and the less information that is gathered, the slower and less precise the first two steps of this process. Alternatively, in a traditional constraint identification process, too much information can be a problem as well, due to human limitation, as discussed above. So, DPM is a great benefit in this regard, because it aggregates the data into a consumable, comparable way every 5 minutes, freeing up your human analytics for problem solving and prioritization, and not data gathering and sorting.   Other Key Tips Also remember that a good tree treats the trunk like a whole unit, with each category occupying a percentage of the overall OEE. Afterall, look back up at the 3 dimensions of OEE in the equation above. For example, the more you see issues with availability, the less you will see issues with scrap, for the machine simply doesn’t have as much time to produce scrap if it is constantly down. The more you see issues with quality loss, the less you should see of productivity loss, because these are simply inversely proportional modes; to say it differently, if a machine is running quickly and seeing few minor maintenance stops, then it is likely to produce more scrap (as well as more good product as well).   Another thing to remember is that even DPM is limited in its capacity to interpret raw data. Even while many magnitudes more efficient than any human gathering and analysis could ever be, there is an upper limit to how much raw data DPM can ingest and analyze before the system gets very expensive. For this reason, you want to ensure your reason trees use only as many reason codes as are required to capture the OEE of a factory site. This will mean using different codes for different types of things, most likely, which is easy to do maintainably across many sites using thing shapes. Keeping things tightly defined and organized is the easiest way to ensure a clean, efficient system for gathering and storing data.   Also remember that data will not need to persist very long once DPM is fully operational and adopted by your factories. DPM ensures that the changes made to the production line to improve efficiency are the highest impact, and the least difficult to implement, meaning that there will be a very rapid return on investment, and a process to ensure future issues are identified and resolved quickly. Data from past issues in the factory won’t be as relevant, and historical data stores can be kept smaller than one might think. It is the power of ingesting data directly into the processing and aggregation process, the automatic reduction of data down into presentable, consumable webpages, that makes DPM and ThingWorx such a great factory solution for optimizing OEE.
View full tip
Welcome to the ThingWorx Analytics Training Course! Through these 11 modules, you will learn all about the functionality of this software, as well as techniques to help you build a successful and meaningful predictive analytics application.
View full tip
ThingWorx Monitoring and Alerting, Part 1 Using Prometheus and Grafana By Tori Firewind, IoT EDC Introduction and Getting Started     As ThingWorx has become a more mature product during the lifetime of the IoT EDC, so too have our dev ops recommendations. As we’ve stated throughout many posts now, testing is a key part of ensuring enterprise readiness, and it occurs at every stage of the process: from unit testing to preserve individual service logic, to integration tests which preserve the functionality of the application as a whole, to user and edge load testing and user experience testing, which ensure enterprise readiness. So testing is a critical component, but the process of dev ops never stops. In order to effectively test the system, a comprehensive monitoring solution is also required.     Once the application is tested and the changes pushed into production, there is no knowing with certainty that everything will run smoothly indefinitely. Random spikes in usage, server bandwidth or availability, any unforeseeable factors like these can come along and cause issues for a system. If these issues aren’t detected and addressed early, then they can very rapidly morph into much larger problems: outages, data loss, inflated data tables which are hard to revert due to their size. It is critical to detect performance issues on a system as early as possible, to have as much information as is necessary to figure out where the problem is heading, and what may have started it. Monitoring is key to a healthy system. CI/CD stands for “Continuous Integration/Continuous Deployment”, a never-ending cycle of improvement. Testing just once before the initial go live isn’t enough. Each system should have automated tests that run continuously, as well as monitors and alerts which reveal problems sooner. Diagnostic tools play a role as well, being the bridge from the end of the dev ops process cycle back to the beginning (monitoring into planning). A good CI/CD dev ops process will ensure that problems are found earlier, fixed more rapidly, and fixed for everyone using the system.       In a fully mature dev ops pipeline, issues are anticipated, discovered and researched before they become production outages or critical issues. These investigations or testing follow-ups produce development tasks (usually bugs, but also features at times) which then start the dev ops cycle all over again. This is why a good, efficient dev ops pipeline is needed, one which allows changes to quickly and safely go from development to production.     This is also why diagnostic tools play a role in the monitoring piece of the dev ops process. They are the bridge between monitoring and planning. Tools like Dynatrace can be configured to provide call stacks and take thread dumps when issues start to occur, before the system is performing so poorly it needs a restart, which happens automatically in a cluster and can clear out any trace of the issue.     Thread dumps are often necessary to diagnosing the root cause of the issue (to permanently fix it), and doing so quickly ensures application stability and availability. That is, after all, the purpose of the dev ops process. Diagnostics is therefore an equally important piece of the dev ops Figure-8-shaped pie, and one which deserves its own spotlight in an article to come.     Every piece of the dev ops process must be viewed as equally important in its own way, lest the dev ops cycle get hung up on bottlenecks of its own. A safe and stable system is not one which never experiences issues, it is one which has a good, efficient plan in place to handle recovery and prevention of repetition. A wholesome dev ops process is a happy dev ops process.   The Monitoring Stack     There are many monitoring options available, but in our experience one of the easiest and most effective monitoring stacks to use with ThingWorx is Prometheus for metrics gathering with Grafana for metrics analysis and review. In a mature monitoring stack, Telegraf is also commonly installed on each VM/host to gather the system metrics (like CPU and Memory usage, things we’ve stated are good metrics of system performance and stability in past articles on scale and size testing) and output them in Prometheus format.     Prometheus is a highly scalable open-source monitoring framework that contains out of the box monitoring and alert capabilities for Kubernetes-based deployments (not covered in this article). Using Prometheus is very simple because the ThingWorx application exposes a metrics endpoint which is formatted directly for use by Prometheus. There is also built-in alerting in Prometheus, but not the ability to form dashboards for reviewing data or screenshotting it for documentation purposes. That’s where Grafana comes into play. Grafana has a preconfigured Prometheus-type data source and many preconfigured dashboard templates for various applications and services. Telegraf is also easily imported into Grafana, as is shown in the section below. The Prometheus targets in the larger diagram are expanded out on the left. For each target, some tool exports the data in a syntax which Prometheus can scrape. For VMs, this can be Telegraf, for Kubernetes, the Node Exporter. JVM has a JMX Exporter, and other tools like CX Server use Graphite. Many apps already have a Prometheus endpoint built-in, like ThingWorx and Zookeeper. Telegraf is not strictly necessary; the node exporter can also be used on VMs, but Telegraf is the more common choice since it is a more mature dev ops tool.     Once Prometheus is scraping the targets, alerting on them can be done with OOTB Prometheus functionality, and dashboards for monitoring can be made easily in Grafana (with built-in support as well). This stack does not include the diagnostics piece, something which triggers thread dumps or the like when issues do occur. There are too many ways to conduct a successful diagnostic piece to cover here.   How to Get Started     Getting started monitoring a ThingWorx application is incredibly easy in the latest versions. Simply open up a browser, and type in the ThingWorx URL, followed by “/Metrics”. At this endpoint, there is a specially formatted response that can automatically be read by the Prometheus monitoring software which contains subsystem and service data. In addition to the application metrics, Prometheus can be configured to collect metrics from a node exporter at the (virtualized) operating system or container (Kubernetes) level as well.     If you haven’t already, install Grafana, install Telegraf as a service, and install Docker Desktop. These are the tools required (in addition to ThingWorx of course) to set-up a simple sandbox system for familiarization with the monitoring stack recommended by PTC. The easiest way to try Prometheus on a local Windows instance is to use Docker. The command for that will be found below, but first open up Docker Desktop to set contextual parameters that the command line will need. Then, modify the configuration file for Telegraf or create one (called telegraf.conf in the same folder as the exe file), and put the following into the file (or uncomment it; the default config file has thousands of lines, so just search for “prometheus”):             Output plugin [[outputs.prometheus_client]] listen = "0.0.0.0:9125"             Alternatively, install the Prometheus Node Exporter tool, which will likely require some additions to the Prometheus config file (not covered here) which we are about to create.     Then, create a configuration file (called prom_config_localhost_scraper.yml in the command to come), add the following (assuming a standard localhost installation of ThingWorx):             # my global config global: scrape_interval: 45s evaluation_interval: 30s scrape_timeout: 30s # scrape_timeout is set to the global default (10s). rule_files: - prom_config_rules.yml scrape_configs: - job_name: thingworx static_configs: - targets: ['host.docker.internal:8080'] basic_auth: username: "Administrator" password: "admin!123456789" metrics_path: /Thingworx/Metrics scheme: http params: x-thingworx-session: - "false" - job_name: prometheus static_configs: - targets: ['localhost:9090'] - job_name: Telegraf # If telegraf is installed, grab stats about the local # machine by default. static_configs: - targets: ['host.docker.internal:9125']                 This example script file uses the host.docker.internal instead of localhost for the server target for ThingWorx because it is running outside of the Docker container which contains Prometheus. This yml file configures Prometheus to monitor both ThingWorx and itself, as well as the server metrics coming from Telegraf (as long as they are configured to push). It’s a sandbox-only configuration, really, as you wouldn’t want to use the Administrator user, or have the password printed in plain text in the config file in a real system. Also note the need for the x-thingworx-session parameter, as runaway sessions which spawn every 30s or so (whatever the scrape interval is) will result in memory issues over time (so we don’t want to use sessions here).     The rules file given here (prom_config_rules.yml) needs to be created separately. This is where all of the alert rules will be defined. This will determine if an alert state is happening, but without configuring the alert manager, there won’t be any notification. That isn’t covered here but is covered extensively in the Grafana docs. Here is an alert example:             groups: - name: alert.rules rules: # Alert for any instance that is unreachable for >5 minutes. - alert: HighMemory expr: mem_used > 14000000 for: 1s labels: severity: page annotations: summary: "High Memory" description: "Localhost Memory Usage is High"             Now, save these files and use Powershell to run the Docker container:             docker run -p 9090:9090 -v C:\<path_to_document>\prom_config_localhost_scraper.yml:/etc/prometheus/prometheus.yml prom/prometheus                 It should download Prometheus and install it in that container (if this is the first time), allowing you to very rapidly deploy it to an endpoint of localhost:9090 by default. If there is an error like the one shown below, this means that you forgot to start Docker Desktop (the application) before opening Powershell. Docker Desktop sets system parameters required for containers to run in a command line (in Linux, it should work if Docker is installed for use by the command line, simple as that).     The localhost endpoints are accessible in a browser. ThingWorx defaults to localhost:8080 endpoint. Prometheus defaults to localhost:9090. Telegraf is on port 9125. Open any of these in a browser tab to see the full monitoring stack. You can see easily if Prometheus is working by clicking “Status” > “Targets” at localhost:9090:     If all of the targets appear as blue and say “last scrape” and a time stamp, then they’re working as expected. If they don’t, ensure you have the right ports, that there aren’t any firewall issues (if things aren’t all on localhost), and that everything is running without errors.     The last step in the process here is to install a dashboard tool like Grafana. Once this is installed and running on localhost:3000 (by default), you can display the data from Prometheus with a few configuration steps the Grafana UI. Highlight over the settings icon in the bottom left of the screen, and then click on “Data sources”. Select the “Add data source” button, and then click on Prometheus. You have to type the URL again  (localhost:9090), but most of the defaults will be ok here, and all you have to do is click “Save and test”.     Now both targets should appear within Grafana, with their metrics showing up throughout the Grafana UI. This data source is what allows for the building of monitoring dashboards.    
View full tip
ThingWorx Monitoring and Alerting, Part 2 Using Prometheus and Grafana By Tori Firewind, IoT EDC Building Dashboards     To add a panel which monitors some component of the ThingWorx application to a dashboard in Grafana, click to add a new panel. Under “Metrics” in the box at the bottom of the screen, select what ThingWorx metrics you wish to monitor (type “thingworx” in the search box to see them all). For example, select the Platform Subsystem memory in use:     Label filters aren’t necessary, though you may want to sort by instance if you are monitoring multiple ones with the same dashboard. You may also want to take some time to format the Y axis, which by default will show in bytes. Go to the formatting panel on the right side and scroll down to the section called “Standard options”. For the Unit dropdown, start typing “data” and then select “bytes (SI)”. This will automatically determine if the bytes you’ve provided should really print as MB or GB based on how large the numbers are.     Rename the panel, modify it in any other way desired, and then click Apply (last 5 minutes):     Once you add the panel, you can watch the memory usage as it is scraped by selecting the refresh option (10s or 30s, whatever makes sense based on your scrape interval).     The viewing window is stored in the URL, so that you can generate a report for a specific interval (like when a test was occurring), and then store that result or share it in a more compact way: http://localhost:3000/d/nleucPv4k/thingworx-monitoring?orgId=1&from=1668528038732&to=1668536503953  (absolute timestamps):     Dashboards are just collections of panels which report on all of the various metrics of performance and stability that exist for single components of a system. This is because there can be quite a few metrics worth watching for each individual component. Most of the third-party tools come with their own dashboards, but the ThingWorx component is one which for now, requires some thought and creativity.     Consider your use case carefully and look over the various subsystems contained within ThingWorx. Each part of an application is localized to specific subsystems, and some are more business critical than others. What will go at the top of your dashboard? Add rows, add panels per row, and see what the many choices are for watching your system.     Don’t forget that with Telegraf running, VM or machine usage metrics are also available for display on a dashboard. Things like overall CPU and Memory usage are critical to determining the health of a system, as we have demonstrated in our own reasoning in past benchmarks and scale tests. You can create a panel to monitor the mem_used versus mem_total, like so:     Another metric from Telegraf worth adding is the CPU usage, which should be given “percentage” for the units and which needs a label filter of cpu = cpu-total. If we do some resizing and drag-and-dropping, then we now have the first row of a dashboard:     See how the Platform usage climbs steadily and is purged in a cycle? That is the Java Garbage Collection mechanism, and it’s important to remember to leave room for spikes on top of those peaks. Data can also be calculated or processed in some way to make it more useful for determining system health and stability.     The data in the picture below uses the formula submitted = completed + number queued + number failed. It shows the current queue on the left Y-axis and the max queue on the right (since the two numbers usually are drastically different). It looks pretty, but it doesn’t really tell us much about the system in this format, so let’s do some math and find a representation that is a bit more helpful.     Performing a “non-negative derivative” calculation over the submitted and the completed queue counts over time allows for us to look at the status of the queue as a velocity. When the “complete” speed appears behind the “submitted” speed for too long at a time, then that means the queue is filling up and will eventually result in data loss.     If we take this one step further and calculate the average of the submitted minus the completed over time, then we can actually predict approximately when the queue will fill up. This can then be displayed on a dashboard in Grafana, or used as the basis for an alert.   What to Monitor     In addition to monitoring the system which ThingWorx runs upon, ThingWorx itself can easily be monitored down to the subsystems level by Prometheus due to the Metrics endpoint. Many applications have support built into the way they format the data for scraping, including the JVM (which exposes Prometheus-formatted metrics with the JMX Exporter) and the OS (which can use the Node Exporter or Telegraf for the same purpose). For these more generic components, there are popular community dashboards which can be downloaded and used in Grafana for data analysis and review.     For ThingWorx, there’s different kinds of data to track: subsystem data (see the list on the right) and non-subsystem data. There’s queue based versus non-queue data. These different metrics can collectively characterize the overall health of the application, depending on the use case.     For instance, if this is a system with very many connected devices, one metric which may be important to track is the number of total devices defined on the Foundation server vs. the number of devices which are currently connected. If there are relays involved, then many devices suddenly going offline can mean a relay has failed. Another example is if the system sizing depends on an assumption that there will only ever be a fraction of the total number of devices connected at a time. Use cases like these could be monitored easily by keeping track of the total vs. the number of connected devices.     Other common indicators of a healthy ThingWorx application might include the value stream and stream queues. These queues should fluctuate over time as the data is ingested and processed, but they should never be growing in size. If the stream queues are growing, then that means the data is writing to the queues faster than the queues can write to the database. Eventually, when the system runs out of resources to keep track of the queues, data will be lost. Having the stream information displayed in a chart can make it very easy to spot an upward trend in resource usage early on, which can catch a blockage or bottleneck that needs attention before it starts to affect the larger system in catastrophic ways later.     Memory usage information from the various subsystems might be something worth tracking, as well as the event queue. These can indicate that the business logic is functioning with room to handle spikes, and that the server has enough memory to service all three dimensions of an IoT application: the ingestion, the business logic and thing-based alerting, and the user experience and UI. If file transfers are a key part of the use case, then the number of concurrent transfers, the average speed of them, the size of the files, all of this kind of stuff can be tracked and charted in Grafana by making use of the ThingWorx metrics which automatically show up there once you import the Prometheus data source.     A mature dashboard used for a production environment might look a little like this: For further reading about subsystem monitoring, check out the Help Center.   How to Alert     The alerting mechanism built-in to Prometheus is incredibly easy to configure, so it might be tempting to generate tons of alert rules. However, remember that the more noise a system makes, the harder it is for those monitoring that system to know when action is really required. Playbooks which document how to respond to alerts, who to contact, how to act, and all the information necessary to handle an alert, should be created as an ongoing part of the DevOps process.     Alerts should fire with the right severity in the subject line, as well as all of the information about the issue that is currently known, presented in a concise way, so that whoever receives the alert starts thinking about the root cause sooner and recovers the system faster. Those who receive the alert should have the ability to facilitate its resolution, and know who is expected to react to any alerts which come in.     In the ThingWorx monitoring stack, Prometheus handles the alert rules and the generation of alerts, but alert filtering and delivery is managed in an external alerts manager.     Generally, you want your alerts to follow a curve. If the current queue size exceeds 50% of the maximum, perhaps that isn’t a huge deal, if the application catches up quickly. How long are spikes in queue processing expected to last? Perhaps if the queue size is over half-full for 10 seconds, 30 seconds, then that means the queue is falling behind and not catching up. Ok, so this might be a warning level alert. When does this become an error? Well, let’s say the queue exceeds 90% of the max queue size. This might want to alert the moment it hits the mark. Now, farther along the curve, it may not take as long before data gets lost.     As the severity of the situation increases, the threshold for alerting should increase as well. That way when errors do alert, it is a sure thing that they require a response immediately. The alerts are then pushed into the “Alerts Manager” for delivery based on your management rules. The Alerts Manager may decide to withhold warnings altogether, or send them to a much smaller mailing list, whatever filtering helps to ensure the right people receive the right alerts, right when they need them.   In Conclusion, A Healthy Application...     Has stable memory usage that fluctuates predictably and doesn’t grow over time. In a system experiencing mild issues, the memory starts to trend upward:     If left unattended, systems like this may eventually experience outages. Finding the issue this early means there is even time to do some digging, debugging, taking of stack traces, and other such troubleshooting steps before the system must be restarted or recovered. That can really make the difference in identifying and resolving before there are real problems.     One metric which makes for good alerting is the total number of failed stream entries, which can indicate there’s an issue writing to the database even before the queue has started to fill up. Other alerts may include warnings and errors based around percentages of memory used or queues filled, which depend on how long the queues take to fill up and how long the state has been at its increased usage.     Prometheus has all of the tools necessary to make this possible across a variety of infrastructures and use cases. Set it up on a local machine and poke around at what ThingWorx metrics are available to meet your monitoring needs.
View full tip
This video is Module 10: ThingWorx Foundation & Analytics Integration of the ThingWorx Analytics Training videos. It gives a brief review of core ThingWorx Platform functionality, and how the Analytics server works on top of the platform. It also describes the process of creating a simple application, complete with a mashup to display the information from a predictive model.
View full tip
This video concludes Module 9: Anomaly Detection of the ThingWorx Analytics Training videos. It gives an overview of the "Statistical Process Control (SPC) Accelerator"
View full tip
This video continues Module 9: Anomaly Detection of the ThingWorx Analytics Training videos. It begins with a ThingWatcher exercise, and concludes by describing Statistical Process Control (SPC). The "SPC Accelerator" will be covered in Module 9 Part 3.
View full tip
This video begins Module 9: Anomaly Detection of the ThingWorx Analytics Training videos. It describes how Thingwatcher can be set up to monitor values streaming from connected assets, and send an alert if its behavior deviates from its 'normal' behavior.
View full tip
This video concludes Module 8: Time Series Modeling of the ThingWorx Analytics Training videos. 
View full tip
This video continues Module 8: Time Series Modeling of the ThingWorx Analytics Training videos. It continues to show how ThingWorx Analytics automatically transforms time series datasets into ones that are ready for machine learning. It also describes the concept of virtual sensors. It finishes by describing the time series dataset that will be used in the following modules.
View full tip
Announcements