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

ThingWorx Navigate is now Windchill Navigate Learn More

IoT & Connectivity Tips

Sort by:
Best Practices in Data Preparation for ThingWorx Analytics Data Preparation is an important phase in the process of Data Analysis when using ThingWorx Analytics. Basically, it is getting your Data from being Raw Data that you might have gathered through your Operational system or from your Data warehouse to the kind of Data ready to be analyzed. In this Document we will be using “Talend Data Preparation Free Desktop” as a Tool to illustrate some examples of the Data Preparations process. This tool could be downloaded under the following Link: https://www.talend.com/products/data-preparation (You could also choose to use another tool) We would also use the Beanpro Dataset in our Examples and illustrations. Checking data formats The analysis starts with a raw data file. The user needs to make sure that the data files can be read. Raw data files come in many different shapes and sizes. For example, spreadsheet data is formatted differently than web data or Sensors collected data and so forth. In ThingWorx Analytics the Data Format acceptable are CSV. So the Data retrieved needs to be inputted into that format before it could be uploaded to TWA Data Example (BeanPro dataset used): After that is done the user needs to actually look at what each field contains. For example, a field is listed as a character field could actually contains none character data. Verify data types Verifying the data types for each feature or field in the Dataset used.  All data falls into one of four categories that affect what sort of analytics that could be applied to it: Nominal data is essentially just a name or an identifier. Ordinal data puts records into order from lowest to highest. Interval data represents values where the differences between them are comparable. Ratio data is like interval data except that it also allows for a value of 0. It's important to understand which categories your data falls into before you feed it into ThingWorx Analytics. For example when doing Predictive Analytics TWA would not accept a Nominal Data Field as Goal. The Goal feature data would have to be of a numerical non nominal type so this needs to be confirmed in an early stage.                 Creating a Data Dictionary A data dictionary is a metadata description of the features included in the Dataset when displayed it consists of a table with 3 columns: - The first column represents a label: that is, the name of a feature, or a combination of multiple (up to 3) features which are fields in the used Dataset. It points to “fieldname” in the configuration json file. - The second column is the Datatype value attached to the label. (Integer, String, Datetime…). It points to “dataType” in the configuration json file. - The third column is a description of the Feature related to the label used in the first column. It points to “description” in the configuration json file. In the context of TWA this Metadata is represented by a Data configuration “json” file that would be uploaded before even uploading the Dataset itself. Sample of BeanPro dataset configuration file below: Verify data accuracy Once it is confirmed that the data is formatted the way that is acceptable by TWA, the user still need to make sure it's accurate and that it makes sense. This step requires some knowledge of the subject area that the Dataset is related to. There isn't really a cut-and-dried approach to verifying data accuracy. The basic idea is to formulate some properties that you think the data should exhibit and test the data to see if those properties hold. Are stock prices always positive? Do all the product codes match the list of valid ones? Essentially, you're trying to figure out whether the data really is what you've been told it is. Identifying outliers Outliers are data points that are distant from the rest of the distribution. They are either very large or very small values compared with the rest of the dataset. Outliers are problematic because they can seriously compromise the Training Models that TWA generates. A single outlier can have a huge impact on the value of the mean. Because the mean is supposed to represent the center of the data, in a sense, this one outlier renders the mean useless. When faced with outliers, the most common strategy is to delete them. Example of the effect of an Outlier in the Feature “AVG Technician Tenure” in BeanPro Dataset:   Dataset with No Outlier: Dataset with Outlier: Deal with missing values Missing values are one of the most common (and annoying) data problems you will encounter. In TWA dealing with the Null values is done by one of the below methods: - Dropping records with missing values from your Dataset. The problem with this is that missing values are frequently not just random little data glitches so this would consider as the last option. - Replacing the NULL values with average values of the responses from the other records of the same field to fill in the missing value Transforming the Dataset - Selecting only certain columns to load which would be relevant to records where salary is not present (salary = null). - Translating coded values: (e.g., if the source system codes male as "1" and female as "2", but the warehouse codes male as "M" and female as "F") - Deriving a new calculated value: (e.g., sale_amount = qty * unit_price) - Transposing or pivoting (turning multiple columns into multiple rows or vice versa) - Splitting a column into multiple columns (e.g., converting a comma-separated list, specified as a string in one column, into individual values in different columns) Please note that: Issue with Talend should be reported to the Talend Team Data preparation is outside the scope of PTC Technical Support so please use this article as an advisable Best Practices document
View full tip
  Hello, IIoT Developers!   9.0 is out—let’s dive right into what’s new with Composer and Mashup Builder. (If you haven’t already checked out what’s new in 9.0 with active-active clustering, be sure to check out this tech tip.) We have a lot of new functionality that we can’t wait for you to start using, so without further ado, let’s begin!   Mashup Builder   In 9.0, we continue to make great advancements to our Mashup Builder and visualization toolset. We’re all about productive developers building the coolest IIoT apps! Mashup in 9.0 with new Line Chart widgets!   Undo/Redo   Ever spent a good half hour arranging a layout, making some data bindings, adding some styles, and once you view the Mashup, you decide you aren’t quite happy with your last few tweaks? The panic sets in when you forget exactly what you changed, and you don’t want to lose all of your edits. What is a developer to do? In older versions of ThingWorx, you might cancel without saving your edits or you might try to surgically get back to a good state. Either way, you were not a happy developer.   ThingWorx 9.0 will make you happy again. All actions in the Mashup are now tracked by an undo/redo buffer. Buttons are now available in the toolbar to help you revert actions. An action history drop-down is also available if you want to undo or redo a few jumps at once. Sometimes, it’s the little things!   Undo and Redo actions now available in the Mashup Builder.   Mobile Settings   For a few releases now, we’ve been upgrading our visualization toolset and examining ways we can be better for desktop and mobile experiences. It starts with our latest layout engine/editor introduced in 8.4 and with new Polymer-based, responsiveness “designed-in” web components introduced in 8.4, 8.5, and 9.0. For the more adventurous folks out there, you can also use Custom CSS to do media queries and influence your layouts based on the viewport settings. There are also custom resolutions and screen orientations available in the Mashup Builder toolbar itself so you can view your content in design mode with each of those targets in mind.   In 9.0, we now have introduced a new Mobile Settings configuration editor on the Mashup. This allows you to define for mobile browsers your scaling and width as well as your height and zoom settings. There are even iOS-specific settings for shortcuts and the status bar.  Mobile Settings Editor and iPhone view of a 9.0 Mashup.   New Configure Bindings Dialog   The heart of any application is the data, and how it is leveraged in the UI. For Mashups, there many good ways to do that with our drag-and-drop functionality or our Bindings panel. But in 9.0, we have completely revamped the Configure Bindings Dialog. You’ll quickly notice when you open the new dialog that it has a more usable interface with more screen real estate to explore services, properties, sources and targets. There is now a good separation between the Widgets, Data and Function sources, which makes things easier to locate and build. You’ll also see, if you’ve made bindings already, the complete map of bindings for your context. New search enhancements and target bindings chip-based filters are also now added.   New Configure Bindings Dialog Another cool feature is that the bindings graph in the dialog will also show you any circular references you may have inadvertently created. If you can see in the diagram below, the red circle icon with a number 1 inside of it—this is almost always a bug, so we may as well tell you about it! New Circular references checking! New Web Components   If you look at almost any IIoT application, you’re almost sure to see a chart. IIoT decisions are always centered around looking at telemetry and KPIs at specific moments of time, events, history, and future projections. ThingWorx has new charts in 9.0 for Line, Bar, and Schedule. They look sharp, they are powerful, and are a true upgrade over the former ThingWorx charts.   Here are some highlights. All are based on D3 framework and follow the PTC Design System. The Line chart also supports sub types of Run, Step, Area, Streamgraph and Scatter plot. The Bar chart also supports a column-based view. The Schedule chart is a great way to visualize downtime events, production orders, machine states, or device alarms. All charts feature responsive layout, advanced performance and data sampling, tooltips, multiple series support, multiple orientations for legends and axis labels, and plenty of styling and data configurations. They also all have great zooming capability for larger data sets including horizontal and vertical pan, drag/lasso zoom, interval controls, range zoom and zoom slider controls. Line Charts with filters, zoom sliders, and markers   Bar Charts with zoom sliders, horizontal and vertical orientations, and configurable legends   Schedule Chart with drilldown and hover tooltips Other Coolness   The team was busy with these highlighted features, but there is so much more in 9.0! For Mashup, we also added: Improved tooltip and icon hover support for all web component-based widgets Accessibility improvements for keyboard navigation and focus New category filters for widget property configuration editors New data tools panel New context menu options New theming options for layout containers Composer For application development outside of the Mashup area, you’ll also notice some new changes in the Composer tool. One of our favorites is the new navigation panels. If you’ve been with ThingWorx for a few releases, you’ve seen many redesigns and updates to the Composer interface. We are constantly evaluating and testing this interface’s design with users to make it a highly productive and intuitive environment. You’ll now see much more horizontal real estate in the Composer because we’ve moved the top header bar into a new left-hand navigation. We’ve also improved the grid resizing in the entity and other list views in the interface to work better with larger result sets. New Composer Layout with updated left-hand navigation One more bonus feature to highlight! We now have quick copy buttons in common places in the interface where you might want to copy entity names or application keys. Just click and that text is in your clipboard. Very handy for searching or making bindings!   Quick copy buttons on entity names     As you can see, plenty of awesome new features and upgrades in the ThingWorx 9.0 application development tools. We also have a brand-new visual SDK available in the 9.0 release so that you can make your own widgets with Polymer and import them into the Mashup Builder. Stay tuned for another Ask Kaya tech tip soon on the SDK.   Like what you see? Have a question? Drop us a line in the comments!   Stay Connected! Kaya  
View full tip
I recently had a customer who wanted to run services on ThingWorx from Power BI to retrieve existing operational data, and we were a bit stumped on how to pass the API key over in the headers, so I did a bit of Googling and pieced together the solution. It's not quite intuitive on the Power BI side, so I thought it would be helpful to share. If you have any other experience with integrating ThingWorx with Power BI, feel free to add a comment.    Prepare ThingWorx Create an Application Key that has Run Time execution access to the services you need. Understand the inputs needed for the service you would like. I'll have examples of none, one, an InfoTable, and multiple inputs.   Power BI Following the following steps in Power BI: 1. In Power BI, create a new blank query   2. On the left, right click on Query1 and go to the Advanced Editor:   3. Replace all of the body content with the following, replacing your API key, appropriate end point, and base URL as needed (this is an example with NO input parameters, I'll follow with examples of other parameters):     let appKey = "your-application-key-here", endpoint = "Things/YourThingNameHere/Services/YourServiceNameHere", baseUrl = "https://YourServerNameHere/Thingworx/", url = Text.Combine({baseUrl,endpoint}), body = "", request = Web.Contents( url, [ Headers = [ appKey = appKey, #"Content-Type" = "application/json", Accept = "application/json" ], Content = Text.ToBinary(body) ] ), Source = Json.Document(request) in Source       4. Click "Done", and now you'll have a warning about how to connect. Click the "Edit Credentials" button. 5. Leave it on Anonymous and click "Connect":   6. You should now see the return data coming from ThingWorx.   Note that I had a little trouble with this authentication initially and it saved the wrong method. To clear that out, go to the ribbon bar item "Data source settings" and select the server and clear it out.   Other Examples Here is an example for sending a single string parameter:   let appKey = "your-application-key-here", endpoint = "Things/YourThingNameHere/Services/YourServiceNameHere", baseUrl = "https://YourServerNameHere/Thingworx/", url = Text.Combine({baseUrl,endpoint}), body = "{""InputParameter"": ""InputValue""}", request = Web.Contents( url, [ Headers = [ appKey = appKey, #"Content-Type" = "application/json", Accept = "application/json" ], Content = Text.ToBinary(body) ] ), Source = Json.Document(request) in Source     Here's an example of sending a string and an integer: let appKey = "your-application-key-here", endpoint = "Things/YourThingNameHere/Services/YourServiceNameHere", baseUrl = "https://YourServerNameHere/Thingworx/", url = Text.Combine({baseUrl,endpoint}), body = "{""InputString"": ""Hello, world!"", ""InputNumber"" : 42}", request = Web.Contents( url, [ Headers = [ appKey = appKey, #"Content-Type" = "application/json", Accept = "application/json" ], Content = Text.ToBinary(body) ] ), Source = Json.Document(request) in Source   Here is an example for sending an InfoTable. Note that you must supply the dataShape with fieldDefinitions. If you're using an existing Data Shape, you can get the JSON by using the service GetDataShapeMetadataAsJSON() that is on the data shape.     let appKey = "your-application-key-here", endpoint = "Things/YourThingNameHere/Services/YourServiceNameHere", baseUrl = "https://YourServerNameHere/Thingworx/", url = Text.Combine({baseUrl,endpoint}), body = "{""propertyNames"": { ""rows"": [ { ""name"": ""FirstEntityName"", ""description"": ""The first entity"" }, { ""name"": ""SecondEntityName"", ""description"": ""The second entity"" }], ""dataShape"": { ""fieldDefinitions"": { ""name"": { ""name"": ""name"", ""aspects"": { ""isPrimaryKey"": true }, ""description"": ""Entity name"", ""baseType"": ""STRING"", ""ordinal"": 0 }, ""description"": { ""name"": ""description"", ""aspects"": {}, ""description"": ""Entity description"", ""baseType"": ""STRING"", ""ordinal"": 0 } } } }}", request = Web.Contents( url, [ Headers = [ appKey = appKey, #"Content-Type" = "application/json", Accept = "application/json" ], Content = Text.ToBinary(body) ] ), Source = Json.Document(request) in Source       If I find any more interesting ways to use Power BI with ThingWorx services, I'll add them on here.  
View full tip
Validator widgets provide an easy way to evaluate simple expressions and allow users to see different outcomes in a Mashup. Using a validator is fairly intuitive for simple expressions, such as is my field blank? But if we need to evaluate a more complex scenario based on multiple parameters, then we can user our validator with a backing service that will perform more complex analytics. To show how services can work in conjunction with a validator widget, let’s consider a slightly more complicated scenario such as: A web form needs to validate that the zip or postal code entered by the user is consistent with the country the user selected. Let’s go through the steps of validating our form: Create a service with two input parameters. Our service will use regex to validate a postal code based on the user’s country.  Here’s some sample code we could use on an example Thing: //Input parameters: Country and PostalCode (strings) //Country-based regular expressions: var reCAD = /^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1} *\d{1}[A-Z]{1}\d{1}$/; var reUS = /^\d{5}(-\d{4})?$/; var reUK = /^[A-Za-z]{1,2}[\d]{1,2}([A-Za-z])?\s?[\d][A-Za-z]{2}$/; var search = ""; //Validate based on Country: if (Country==="CAD")                search = reCAD.exec(PostalCode); else if (Country==="US")                search = reUS.exec(PostalCode); else if (Country==="UK")                search = reUK.exec(PostalCode); (search == null) ? result = false: result = true; Set up a simple mashup to collect the parameters and pass them into our service Add a validator widget Configure the validator widget to parse the output of the service. ServiceInvokeComplete on the service should trigger the evaluation and pass the result of the service into a new parameter on the widget called ServiceResult (Boolean). The expression for the evaluator would then be: ServiceResult? true:false Based on the output of the validator, provide a message confirming the postal code is valid or invalid Add a button to activate the service and the validator evaluation Of course, in addition to providing a message we can also use the results of the validator to activate additional services (such as writing the results of the form to the database). For an example you can import into your ThingWorx environment, please see the attached .zip file which contains a sample mashup and a test thing with a validator service.
View full tip
How to Scale Vertically and Horizontally, and When to Use Sharding Written by Mike Jasperson, VP of IOT EDC   Deployment architecture describes the way in which an IOT application is deployed, or where each of the components are hosted on the network. There are deployment architecture considerations to make when scaling up an application. Each approach to deployment expansion can be described by the “eggs in a basket” analogy: vertical scale is like one person carrying a bigger basket, horizontal scale is like one person carrying more baskets, and sharding is like more than one person carrying the baskets (see below).   All of these approaches result in the eggs getting from point A to point B (they all satisfy the use case), but the simplest (vertical scale) is not necessarily the best. Sure, it makes sense on paper for one person to carry everything in one big basket, but that doesn’t ensure that all of the eggs arrive intact. Selecting the right deployment architecture is a way to ensure the use cases are satisfied in the best and most efficient ways possible, with the least amount of application downtown or data loss.   Vertical Scale - a.k.a. "one person carrying a bigger basket" The most common scalability approach is to simply size the IOT server larger, or scale up the server. This might mean the server is given additional CPU cores, faster CPU clock speeds, more memory, faster disks, additional network bandwidth or improved network cards, and so on. This is a very good idea  when the application logic is increased in complexity, when more data is therefore needed in memory at a time, or when the processing of said data has to occur as quickly as possible. For example, adding additional devices to the fleet increases the size of the “Thing Model” in the process and will require additional heap memory be available to the Foundation server.   However, there are limitations to this approach. Only so many concurrent operations and threads can be performed at once by a single server. Operations trying to read and write to the disks at once can introduce bottlenecks and reduce server performance. Likewise, “one person, one basket” introduces a single-point-of-failure operating risk. If for some reason the server’s performance does degrade or cease altogether, then all of the “eggs” go down with it. Therefore, this approach is important, but usually not sufficient on its own for empowering an enterprise level deployment.   Horizontal Scale - a.k.a. "one person, with two or more baskets" As of ThingWorx version 9.0, Foundation servers can be deployed in clusters, meaning more baskets to carry the eggs. More baskets means that if even one of these servers is active, the application remains up in the event of an individual node failure or maintenance. So clustered deployments are those which facilitate High Availability.   Clustered servers save on some resources, but not others. For instance, every server in a cluster will need to have the same amount of memory, enough to store the entire Thing Model. Each of the multiple baskets in our analogy has to have the same type of eggs. One basket can’t have quail eggs if the rest have chicken eggs. So, each server has to have an identical version of the application, and therefore enough memory to store the entire application.   Also keep in mind that not all application business logic can scale horizontally. Event queues are local to each ThingWorx node, so the events generated within each node are processed locally by that particular node, and not the entire network (examples are timer and scheduler-based activities). Likewise, data ingestion done through an extension or other background process, like MQTT, emits events within a node that therefore must be processed by that particular node, since that's where the events are visible. On the other hand, load distribution that happens external to ThingWorx in either the Connection Server (for AlwaysOn based data coming from ThingWorx SDKs, EMS, eMessage agents, or Kepware) or REST API calls through a load balancer (i.e. user activity) will be distributed across the cluster, facilitating greater scaling potential in terms of userbase and mashup complexity. Also note that batched data will be processed by the node that received it, but different batches coming through a connection server or load balancer will still be distributed.   Another consideration with clusters pertains to failure modes. While each node in the cluster shares a cache for many things, Stream and Value Stream queues are only stored locally. In the event of a node failure, other nodes will pick up subsequent requests, but any activity already queued on the failed node will be lost. For use cases where each and every data point is critical, it is important to size each node large enough (in other words, to vertically scale each node) such that queue sizes are constantly kept low and the data within them processed as quickly as possible. Ensuring sufficient network and database throughput to handle concurrent writes from the many clustered nodes is key as well.   Once each node has enough resources to handle local queues, the system is highly available with low risk for outages or data loss. However, when multiple use cases become necessary on single deployments, horizontal scaling may no longer be enough to ensure things run smoothly. If one use case is logic-heavy, something non-time-critical which processes data for later consumption, it can use too many resources and interfere with other, lighter but more time-critical use cases. Clustering alone does not provide the flexibility to prioritize specific operations or use cases over others, but sharding does.   Sharding - a.k.a. "more than one person carrying baskets" “Sharding” generally refers to breaking up a larger IOT enterprise implementation into smaller ones, each with its own configuration and resources. More server maintenance and administration may be required for each ThingWorx implementation, but the reduction in risk is worth it. If each of the use cases mentioned above has its own implementation, then any unexpected issues with the more complex, analytical logic will not affect the reaction time of operators to time-sensitive matters in the other use case. In other words, “don’t keep all your eggs in one basket”.   The best places to break up an implementation lie along logical boundaries already accepted by the business. Breaking things down in other ways might look nice on paper, but encouraging widespread adoption in those cases tends to be an uphill battle.   In connected products use cases, options for boundaries could be regional, tied more towards business vertical, or centered around different products or models.  These options can be especially beneficial when data needs to stay in particular countries or regions due to regulatory requirements. In connected operations use cases, the most common logical boundaries would be site-based, with smaller IOT implementations serving just a smaller number of related factories in a particular area. Use-case or product-line boundaries can also make sense here, in-line with the above comments about keeping production-critical or time-sensitive use cases isolated from interference from business-support and analysis use cases.     Ideally, a shard model will put the IOT implementation “closer” to both the devices communicating with it and the users that interact with the data. This minimizes the amount of data to be sent or received over long distances, reducing the impact from bandwidth and latency on performance. When determining which approach is best, consider that smaller, more focused implementations offer more flexibility, but are harder to manage. Having different versions of the same applications deployed in multiple places can easily become a maintainability nightmare. It’s therefore best not to combine a regional model with a use case model when it comes to determining sharding boundaries. Also consider using deployment automation tools like Solution Central. These enable tracking and managing version-controlled deployments to multiple IOT implementations, whether they are deployed on-premise, or in the cloud, giving one central location of all source code.   Another benefit to sharding is the focused investment of server resources in a more targeted way. For instance, if one region is larger than another, it may need more CPU and memory. Or, perhaps only part of an application requires High Availability, the time-critical use cases which are best suited to small, clustered deployments. The larger, analysis-centered use cases can then remain non-clustered (but still vertically scaled of course). Sharding can also make access control simpler, as those who need access to only one region or use case can just be given a user account on that particular shard.   However, certain use cases need data from more than one shard in order to operate, turning the data storage and access control benefits into challenges. Luckily, ThingWorx has an excellent toolkit for overcoming such issues. For one thing, REST API calls are readily available in ThingWorx, allowing each shard to exchange information with each other, as well as other enterprise data systems, like ERP or Service Ticketing. Sometimes, lower-level data replication strategies are the way to go, say if downsampling or data transfer from one store to another is necessary, and built-in database tools can more easily handle the workload. Most of the time, however, REST API calls are used to define the business logic within the application layer so that copying data actively between shards is unnecessary, using fewer resources to control what information is shared overall.   There are several design approaches for REST API communication between shards, the two most common being the “peer” model and the “layered” model. In a peer model, one shard may call upon another shard using REST whenever it needs more information. In a layered model, there are “front-line” shards which handle most (if not all) of the device communication and time-critical use cases, things which require only the information in one shard to operate. Then there are also “back-line” shards that aggregate data from the many front-line shards, performing any operations that are less time-sensitive and more complex or analytical.   For any of these approaches, it remains important to keep your data archival and purge strategy in mind. It is a best practice in ThingWorx to only retain as much data as is absolutely necessary, purging the rest periodically. If the front-line shards only ever need the last 7 days of raw data for 5 properties, plus the last 52 weeks of min/max/average data, then implementing an approach where each shard computes the min/max/average values and then archives the older data to a shared “data lake” before purging it would be ideal. This data lake then serves as the data store for all back-line shard operations.   There is also the option to consider sharing some infrastructure between ThingWorx instances when using sharding in a deployment, which can create more flexible, scalable architectures, but can also introduce issues where more than one shard is affected when issues occur on only one shard. For instance, a common shared infrastructure piece is at the database level; each ThingWorx instance needs its own database, but a single database server instance (such as a PostgreSQL HA cluster) could serve separate database namespaces to multiple ThingWorx instances. This is an attractive option where an existing enterprise-scale database infrastructure with experienced DBAs is already in place.   Similarly, load balancers can often be configured to manage load for multiple servers or URLs. If properly configured, an experienced load balancer could direct traffic for multiple applications, but it can also create a bottleneck for inbound connections if not properly sized. Load balancers designed for High Availability can also be considered. Apache Zookeeper is another tool often deployed once for an entire cluster to monitor the health and availability of individual components, or to vote them in or out of operations if problems are detected. With all of these options, remember that sharing infrastructure increases the chances of sharing issues from one ThingWorx system to the next, which can reduce the overall infrastructure complexity at the cost of increased administrative complexity.   Bringing it All Together Vertical and Horizontal scale are both effective ways to add more capacity and availability to software implementations, but there are typically some diminishing returns in the investment of additional infrastructure. For example, consider two large, vertically-scaled implementations – one running on a VM with 64 vCPUs and 256 GiB RAM, and another running on a VM with 96 vCPUs and 384GiB of RAM. While the 96-core server has 1.5 times the compute capacity, in sizing tests with 1 million simulated assets, these two systems tend to fall behind on WebSocket execution at approximately the same point.     In a horizontal scale example, with two nodes each sized the same (64 vCPU and 256GiB RAM), one would expect High Availability to occur, where one node picks up the other’s slack in a failover scenario. However, what if that singular node can’t handle the entire workload? Should both machines be sized vertically such that either can take on the full load, and if so, then what is the cost-benefit of that? It would be less expensive in this case to have a third server.     Optimizing the deployment architecture for a ThingWorx application will therefore usually involve a blended approach. With more than two nodes, High Availability is more readily obtained, as two servers can almost certainly share the load of the third, failed node. Likewise, some workload aspects do not scale well until multiple additional nodes are added. For instance, spreading out the user load from mashup requests across multiple nodes to give the singleton more resources for the tasks it alone can perform doesn’t have much benefit if there are just two nodes.   However, with horizontal scaling alone, the servers may still need to be vertically scaled larger than is ideal in terms of cost. Each one has to hold the entire Thing Model in memory, which means that sometimes, some of the nodes may be oversized for the tasks actually performed there. Sharding allows for each node to have a different Thing Model as necessary based around what boundaries are selected, which can mean saving on costs by sizing each server only as large as it really needs to be.   So, a combination of approaches is typically the best when it comes to deployment architecture. The key is to break things up as much as possible, but in ways that make sense. Determine where the boundaries of the shards will be such that each machine can be as light and focused as possible, while still not introducing more work in terms of user effort (having to access two system to get the job done), application development (extra code used to maintain multiple systems or exchange information between them), and system administration (monitoring and maintaining multiple enterprise systems).   Find the right balance for your systems, and you’ll maximize your cost-benefit ratio and get the most out of your ThingWorx application. Happy developing!
View full tip
Create Your Application Guide UI Part 1    Overview   This project will introduce the ThingWorx Mashup Builder. Following the steps in this guide, you will learn how to use this tool to create a Graphical User Interface (GUI) for your IoT Application. We will teach you how to rapidly create and update a Mashup, which is a custom visualization built to display data from devices according to your application's business and technical requirements. NOTE: This guide's content aligns with ThingWorx 9.3. The estimated time to complete ALL 5 parts of this guide is 30 minutes.    Step 1: Create New Mashup   The Mashup Builder is a drag-and-drop environment with a What You See Is What You Get (WYSIWYG) interface. With the Mashup Builder you can quickly and easily create a visualization of your IoT data. In this step, we'll explain various options to customize your application GUI. Click Browse > VISUALIZATION > Mashups.   Click + New. You are now on the New Mashup pop-up window.           Layout Options When creating your UI, you must choose whether you want a Responsive, Static, or Responsive (Advanced) Mashup, depending on the resolutions of the displays you want your application users to utilize when running your application. Mashup Layout Description When to Use Responsive Expands to the resolution of the display in an even more dynamic manner than the Responsive (Legacy) option. Previously-labeled as Responsive (Advanced), this is now the default option with modifications to the Mashup Builder interface versus previous versions. For instance, divisions such as a header or footer are available with the Template options at the bottom of the pop-up. Static (Legacy) Sized to the dimensions that you define. Static Mashups are appropriate when your users have a standard device on which they’ll be utilizing your application, such as a smartphone or tablet. When displayed in a lower resolution you will see scroll bars, in a higher resolution there will be unused space around the Mashup. Responsive (Legacy) Expands to the resolution of the display without leaving any unused space around the Mashup. Responsive Mashups should be utilized when you anticipate that users will interface with your application through various-sized screens. Responsive Mashups should always be tested at various resolutions to ensure optimum display of your IoT data.   Keep the default of Responsive (with NO Responsive Templates chosen), and click OK in the pop-up window. In the Name field, enter appui_mashup.   If the Project is not already set, search for and select PTCDefaultProject.  At the top, click Save.   At the top, click Design. This is the Mashup Builder user interface we will use for the remainder of this guide.              6. On the left, click the "left arrow" Collapse icon to cause the Composer Navigation to slide-out, revealing more room for the Mashup Builder interface.         Step 2: Mashup Builder Sections Now that you've launched the Mashup Builder, you'll need an understanding of the layout and configuration options.     NOTE: Section 1 in the top-left has a drop-down arrow you can click to reveal additional sections if your screen resolution is too small to show all of Widgets, Layout, and Explorer. There is also the Mashups tab in Section 1, but it is not covered in this guide.   Mashup Builder Section Description 1a Widgets Widgets provides a list of every graphical element within the platform. There are a wide variety of selections, from grids to graphs to text boxes to buttons. There is also a Filter Widgets field where you can enter the name of a particular Widget to sort the list. 1b Layout Layout is used to divide your Mashup into logical sub-sections. 1c Explorer Explorer allows you to reach any individual element of a Mashup. This can be helpful when multiple Widgets are overload on top of each other in the central Canvas window, making it difficult to click on them individually. 2 Canvas This is an area into which you can drag-and-drop Widgets to your desired location to build your application UI. You can also drag-and-drop data onto the Widgets in the Canvas. 3a Data Data is fundamental to any Mashup that wants to display ThingWorx IoT data, as it allows you to bind backend-data to particular Widgets. 3b Session Session provides access to Session Parameters, which are similar to global variables that may be used across multiple Mashups, such as cookies or security information for a logged-in User. 3c User User provides access to the User Extensions. User Extensions are the Properties of the logged-in User and can be used on the Client side and/or the Server side. 4a Properties Properties displays the Properties for the selected Mashup or Widget. These Properties allow you to perform a variety of modifications to Widgets, such as setting its exact position. 4b Style Properties Style Properties are a sub-set of Properties dealing with items such as changing color. 5a Bindings As data connections are made to various Widgets, the Bindings window will show these links in an easy-to-understand 'arrow' format. For instance, if a button press causes a Thing’s Service to be called, then you’ll see a connection from the Button Widget’s *Clicked* Event over to the Thing’s Service. 5b Reminders Reminders points out issues with your Mashup, such as unbound but required Properties, which often must be fixed before the Mashup can be saved. 6a Data Properties Data Properties displays properties of the selected data element. This can be helpful, for instance, when you want something to be triggered only when something else has completed. In that scenario, you’d look for the ServiceInvokeCompleted Event in this bottom-right area. 6b Functions Functions provides the ability to write custom business logic within the Mashup itself.   Step 3: Introducing Widgets   The primary way in which you'll create the GUI for your IoT application is with Widgets. Widgets are self-contained graphical elements that you can drag-and-drop onto the central Canvas area. Once placed on the Canvas, you can: Modify Widget layout Resize Widgets Bind Data to Widgets Combining several Widgets together will allow you to quickly and easily create a functional GUI for your IoT application. Widget Name Widget Example Picture Description Button   The Button Widget triggers an Event when it is clicked. Typically, this Event will be used to trigger a Service to either push or pull data from the platform’s backend. Checkbox   The Checkbox Widget provides a simple box which can be either set or not-set. You primarily use a Checkbox when you’re setting or displaying Boolean data. Gauge   The Gauge Widget provides a more “graphically interesting” way to display a numerical value. You can set the minimum and maximum values which a Gauge displays, or style a Gauge so that different areas are different colors. Label   The Label Widget displays a non-user-interactable string within your Mashup. You can use this to create headings or descriptions for parts of your Mashup. Text Field   The Text Field Widget is a small, one-line area into which you can either accept an input string from the User or display a string from the platform’s backend. Combining a few of the basic Widgets described above allows you to create a Mashup for your IoT application. However, without data being supplied to these Widgets from the platform's backend, they're just pretty graphics. In the next section, we will introduce a few of the Mashup Services that enable bidirectional data flow between your GUI and device data.   Click here to view Part 2 of this guide.     
View full tip
A Feature - a piece of information that is potentially useful for prediction. Any attribute could be a feature, as long as it is useful to the model. Feature engineering – Feature engineering is the process of transforming raw data into features that better represent the underlying problem to the predictive models, resulting in improved model accuracy on unseen data. It’s a vaguely agreed space of tasks related to designing feature sets for Machine Learning applications. Components: First, understanding the properties of the task you’re trying to solve and how they might interact with the strengths and limitations of the model you are going to use. Second, experimental work were you test your expectations and find out what actually works and what doesn’t. Feature engineering as a technique, has three sub categories of techniques: Feature selection, Dimension reduction and Feature generation. Feature Selection: Sometimes called feature ranking or feature importance, this is the process of ranking the attributes by their value to predictive ability of a model. Algorithms such as decision trees automatically rank the attributes in the data set. The top few nodes in a decision tree are considered the most important features from a predictive stand point. As a part of a process, feature selection using entropy based methods like decision trees can be employed to filter out less valuable attributes before feeding the reduced dataset to another modeling algorithm. Regression type models usually employ methods such as forward selection or backward elimination to select the final set of attributes for a model. For example: Project Development decision-tree:                                                  Dimension Reduction: This is sometimes called feature extraction. The most classic example of dimension reduction is principle component analysis or PCA. PCA allows us to combine existing attributes into a new data frame consisting of a much reduced number of attributes by utilizing the variance in the data. The attributes which "explain" the highest amount of variance in the data form the first few principal components and we can ignore the rest of the attributes if data dimensionality is a problem from a computational standpoint. Feature Generation or Feature Construction: Quite simply, this is the process of manually constructing new attributes from raw data. It involves intelligently combining or splitting existing raw attributes into new one which have a higher predictive power. For example a date stamp may be used to generate 2 new attributes such as AM and PM which may be useful in discriminating whether day or night has a higher propensity to influence the response variable. Feature construction is essentially a data transformation process. Tips for Better Feature Engineering Tip 1: Think about inputs you can create by rolling up existing data fields to a higher/broader level or category. As an example, a person’s title can be categorized into strategic or tactical. Those with titles of “VP” and above can be coded as strategic. Those with titles “Director” and below become tactical. Strategic contacts are those that make high-level budgeting and strategic decisions for a company. Tactical are those in the trenches doing day-to-day work.  Other roll-up examples include: Collating several industries into a higher-level industry: Collate oil and gas companies with utility companies, for instance, and call it the energy industry, or fold high tech and telecommunications industries into a single area called “technology.” Defining “large” companies as those that make $1 billion or more and “small” companies as those that make less than $1 billion.   Tip 2: Think about ways to drill down into more detail in a single field. As an example, a contact within a company may respond to marketing campaigns, and you may have information about his or her number of responses. Drilling down, we can ask how many of these responses occurred in the past two weeks, one to three months, or more than six months in the past. This creates three additional binary (yes=1/no=0) data fields for a model. Other drill-down examples include: Cadence: Number of days between consecutive marketing responses by a contact: 1–7, 8–14, 15–21, 21+ Multiple responses on same day flag (multiple responses = 1, otherwise =0) Tip 3: Split data into separate categories also called bins. For example, annual revenue for companies in your database may range from $50 million (M) to over $1 billion (B). Split the revenue into sequential bins: $50–$200M, $201–$500M, $501M–$1B, and $1B+. Whenever a company falls with the revenue bin it receives a one; otherwise the value is zero. There are now four new data fields created from the annual revenue field. Other examples are: Number of marketing responses by contact: 1–5, 6–10, 10+ Number of employees in company: 1–100, 101–500, 502–1,000, 1,001–5,000, 5,000+ Tip 4: Think about ways to combine existing data fields into new ones. As an example, you may want to create a flag (0/1) that identifies whether someone is a VP or higher and has more than 10 years of experience. Other examples of combining fields include: Title of director or below and in a company with less than 500 employees Public company and located in the Midwestern United States You can even multiply, divide, add, or subtract one data field by another to create a new input. Tip 5: Don’t reinvent the wheel – use variables that others have already fashioned. Tip 6: Think about the problem at hand and be creative. Don’t worry about creating too many variables at first, just let the brainstorming flow.
View full tip
This post covers how to build and operationalize a time series model using Thingworx Analytics. A lookback window is used to read multiple previous rows before the current one, and base the prediction on those lookback rows.   In this example we use time series data to predict water flow for different water pumps in a system.   There is a full explanation of the method attached, also all necessary resources are included in the attached files.
View full tip
ThingWorx Foundation Flow Enable customers using Azure to take advantage of Azure services Access hundreds of Azure system connectors by invoking Azure Logic Apps from within ThingWorx Flow Execute Azure functions to leverage Azure dynamic, serverless scaling and pay just for processing power needed Access Azure Cognitive AI services for image recognition, text to voice/voice to text, OCR and more Easily integrate with homegrown and commercial solutions based on SQL databases where explicit APIs or REST services are not exposed Automatically trigger business process flows by subscribing to Windchill object class and instance events Provide visibility to mature PLM content (such as when a part is released) to downstream manufacturing and supply chain roles and systems Easily add new actions by extending functionality from existing connectors to create new actions to facilitate common tasks Inherit or copy functionality from existing actions and change only what is necessary to support new custom action Azure Connector SQL Database Connector Windchill Event Trigger Custom Action Improvements Platform Composer: Horizontal tab navigation is back!  Also new Scheduler editor. Security: TLS 1.2 support by default, new services for handling expired device connections New support for InFlux 1.7 and MSSQL 2017 * New* Solution Central Package, publish and upload your app with version info and metadata to your tenancy of Solution Central in the PTC cloud Identify missing dependencies via automatic dependency management to ensure your application is packaged with everything required for it to run on the target environments Garner enterprise-wide visibility of your ThingWorx apps deployed across the enterprise via a cloud portal showcasing your company’s available apps, their versions and target environments to foster a holistic view of your entire IIoT footprint across all of your servers, sites and use cases Solution Central is a brand-new cloud-based service to help enterprises package, store, deploy and manage their ThingWorx apps Accelerate your application deployment Initially targeted at developers and admins in its first release, Solution Central enables you to: Mashup Builder 9 new widgets, 5 new functions. Theme Editor with swappable Mashup Preview Responsive Layout enhancements including new settings for fixed and range sizes New Builder for custom screen sizes, new Widget and Style editors, Canvas Zoom Migration utility available for legacy applications to help move to latest features Security 3 new built-in services for WebSocket Communications Subsystem: QueryEndpointSessions, GetBoundThingsForEndpoint, and CloseEndpointSessions Provide greater awareness of Things bound to the platform Allow for mass termination of connections, if necessary Can be configured to automatically disconnect devices with expired authentication methods Encrypting data-in-motion (using TLS 1.2) is a best practice for securely using ThingWorx For previous versions, the installer defaulted to not configuring TLS; ThingWorx 8.5 and later installers will default to configuring TLS ThingWorx will still allow customers to decline to do so, if desired Device connection monitoring & security TLS by default when using installer   ThingWorx Analytics Confidence Model Training and Scoring (ThingWorx Analytics APIs) Deepens functionality by enabling training and scoring of confidence models to provide information about the uncertainty in a prediction to facilitate human and automated decision making Range Property Transform and Descriptive Service Improves ease of implementation of data transformations required for common statistical process control visualizations Architecture Simplification Improves cost of ownership by reducing the number of microservices required by Analytics Server to reduce deployment complexity Simplified installation process enables system administrators to integrate ThingWorx Analytics Server with either (or both) ThingWorx Foundation 8.5 and FactoryTalk Analytics DataFlowML 3.0.   ThingWorx Manufacturing and Service Apps & Operator Advisor Manufacturing common layer extension - now bundling all apps as one extension (Operator Advisor, Asset Advisor, Production KPIs, Controls Advisor) Operator Advisor user interface for work instruction delivery Shift and Crew data model & user interface Enhancements to Operator Advisor MPMLink connector Flexible KPI calculations Multiple context support for assets   ThingWorx Navigate New Change Management App, first in the Contribute series, allows a user to participate in change request reviews delivered through a task list called “My Tasks” BETA Release of intelligent, reusable components that will dramatically increase the speed of custom App development Improvements to existing View Apps Updated, re-usable 3D viewing component (ThingView widget) Support for Windchill Distributed Vaults Display of Security Labels & Values   ThingWorx Azure IOT Hub Connector Seamless compatibility of Azure devices with ThingWorx accelerators like Asset Advisor and custom applications developed using Mashup Builder. Ability to update software and firmware remotely using ready-built Software Content Management via “ThingWorx Azure Software Content Management” Module on Azure IoT Edge. Quick installation and configuration of ThingWorx Azure IoT Hub Connector, Azure IoT Hub and Azure IoT Edge SCM module.   Documentation ThingWorx Platform ThingWorx Platform 8.5 Release Notes ThingWorx Platform Help Center ThingWorx 8.5 Platform Reference Documents ThingWorx Connection Services Help Center   ThingWorx Azure IoT Hub Connector ThingWorx Azure IoT Hub Connector Help Center   ThingWorx Analytics ThingWorx Platform Analytics 8.5.0 Release Notes Analytics Server 8.5.1 Release Notes ThingWorx Analytics Help Center   ThingWorx Manufacturing & Service Apps and ThingWorx Operator Advisor ThingWorx Apps Help Center ThingWorx Operator Advisor Help Center   ThingWorx Navigate ThingWorx Navigate 8.5 Release Notes Installing ThingWorx Navigate 8.5 Upgrading to ThingWorx Navigate 8.5 ThingWorx Navigate 8.5 Tasks and Tailoring Customizing ThingWorx Navigate 8.5 PTC Windchill Extension Guide 1.12.x ThingWorx Navigate 8.5 Product Compatibility Matrix ThingWorx Navigate 8.5 Upgrade Support Matrix ThingWorx Navigate Help Center     Additional Information Helpcenter ThingWorx eSupport Portal ThingWorx Developer Portal PTC Marketplace The National Instruments Connector can be found on PTC Marketplace  
View full tip
This video will provide you with a brief introduction to the New Composer interface, which has been made available in the 7.4 and later releases of the ThingWorx Platform.  For complete details on what functionality is available within this next generation composer interface, and to also see what lies ahead on our road map, please refer to the following post in the ThingWorx Community: NG Composer feature availability
View full tip
This video builds upon the mashup created in the basic session, and strives to create a more polished, user-friendly interface that is ready for deployment. In part 1, we’ll take a look at advanced layout designs and include a more varied set of widgets to help draw attention to some of the more pertinent properties being captured within the mashup.   For full-sized viewing, click on the YouTube link in the player controls. Visit the Online Success Guide to access our Expert Session videos at any time as well as additional information about ThingWorx training and services.  
View full tip
Video Author:                     Stefan Taka Original Post Date:            July 14, 2017 Applicable Releases:        ThingWorx 7.4   Description: This video will provide you with a brief introduction to the New Composer Interface, which has been made available in the 7.4 and later releases of the ThingWorx Platform.  For complete details on what functionality is available within this next generation composer interface, and to also see what lies ahead on our road map, please refer to the following post in the Community.   NG Composer feature availability  
View full tip
In this blog I will be covering the initial setup of ThingWorx Android SDK with a sample app (supplied with the Android SDK) and set it up with a web based revision control system like Bitbucket's (free account plan). I'll also be covering quick information on how to enable the HTTPS connection for the ThingWorx server on Windows platform. This will allow for secured connection to the ThingWorx server from the Android application. Do note this is only a reference guide for setting it up with revision control system, you’re free to choose to setup the Android Studio without Bitbucket or with any other revision control system. It’ll be just fine to have a local Git/SVN/Perforce etc. to manage the code repository, setting Android Studio with Bitbucket is officially not supported. Pre-requisite: 1. Download and unzip the ThingWorx Android SDK from https://support.ptc.com 2. An account with Bitbucket is required 3. Download and install Android Studio Project Setup 1. Unzip the downloaded Android SDK on a local drive 2. Start the Android Studio > Import project > navigate to the sample applications location provided with the ThingWorx Android SDK e.g. Thingworx-Android-SDK-X.x.x\samples 3. Select one of the sample application e.g. androidShell, with ThingWorx Android SDK X.x.x there are 3 sample applications currently available when the Android SDK is downloaded: a. Android File Brwoser b. Android Shell c. Android Steam Thing 4. For this blog I'll be setting up the androidShell Android Application 5. Do note that all the sample projects are built using Gradle, so while importing if required select Gradle as the build system for the sample application 6. Once imported successfully in Android Studio you should be able to see the Android project and its file structure like so 7. We'll need an account with Bitbucket, create one if you don't have already 8. Logon to Bitbucket and create a team and new repository under that team 9. Navigate to the repository created in Bitbucket 10. Create a local GIT code repo if you don't already have one, and copy over all the contents from the Android SDK x.x.x.zip to that location 11. On your local machine open a command prompt and navigate to the drive where the local GIT's code repository resides, i.e. the folder where you unzipped the android SDK and execute the commands as mentioned: a. git remote add origin https://<accountName@bitbucket.org>/<teamName>/<projectName>.git b. git push -u origin master Note: This will add the contents of your local GIT repository to the empty code repository you’ve created under the team on Bitbucket. 12. You can also use SourceTree UI application on windows for creating, GIT and Mercury based code repository and connect it to your Bitbucket account 13. On successful commit following will be logged in the command prompt Enabling HTTPS on Tomcat and connecting to Android Application Securing Tomcat on Windows You can skip this section if you already have Tomcat running ThingWorx configured for HTTPS connection. 1. Execute the command in a command prompt C:\>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -keystore C:\KeystoreTomcat\tomcat.keystore Note: Executing above step will require you to add additional information to the keystore like, Org name, full name location, etc. 2. Edit the <tomcatInstallation>\conf\server.xml file   <Connector   port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"               maxThreads="200" SSLEnabled="true" scheme="https" secure="true" keystoreFile="C:\KeystoreTomcat\tomcat.keystore" keystorePass="<giveYourPasswordHere>" clientAuth="false" sslProtocol="TLS">       <!-- <SSLHostConfig>             <Certificate certificateKeystoreFile="conf/localhost-rsa.jks"                         type="RSA" />         </SSLHostConfig>-->     </Connector> 3. Restart the tomcat service Note: For detailed information on securing the Tomcat on Windows refer to SSL/TLS Configuration How-TO . Note HTTPS setup is only for the Tomcat where ThingWorx is deployed and does not involve certificate setup on the Android Application side Finally,to test if the HTTPS setup was successful or not navigate to https://<serverName/IP>:8443/Thingworx in a web browser. Port 8443 is the default HTTPS port. Starting and connecting Android Application to ThingWorx Now that we have a working secured Tomcat and Android Studio setup with the sample Android Application, androidShell. Let's build and run the application using an emulated Android device in Android Studio 1. Navigate to https://localhost:8443/Thingworx > Import/Export > Import from file and import the Thing entity which will connect to the SampleThing when you’ll run the Android application, for e.g. I imported the Thingworx-Android-SDK-X.X.X\samples\android-shell\entity\Things_AndroidSampleThing.xml because I will be running the androidShell application 2. Attempting to run the Android application without the entity created in ThingWorx first, Thing will show as unbound in RemoteThing. 3. Create an AppKey in ThingWorx > Security > Application Keys with sufficient rights 4. Go to the Android Studio's toolbar and click on AVD Manager icon 5. This will open the Android Virtual Device Manager and lets you create a virtual Android device 6. You can of course use your own actual device to connect over USB and install and test the application on actual hardware 7. If you already have a Virtual or actual device connected to the system, click on Make Project icon in the toolbar 8. Once the Make finishes run the sample application, in my case androidShell application with the Run icon, like so 9. You may now be prompted with the options to select a device virtual or actual 10. Select as desired and click OK 11. This will now launch the application on the selected device, I have selected to launch on the virtual device which will start and emulated Android Device 12. When initiating/running the application for the first time you will be directed to the Settings screen allowing you to enter the connection URI and the Application Key to connect to the ThingWorx server 13. You have to follow one of the following two URI schemes while attempting to connect to a ThingWorx Server a. For HTTP connection use : ws://<machineIP/Name>:8080/Thingworx/WS b. For HTTPS connection use : wss://<machineIP/Name>:8443/Thingworx/WS Note: Ports may differ as these are the default ports, if you are running ThingWorx on different port enhance the URI accordingly 14. Since my ThingWorx is reachable on HTTPS connection i'll use the HTTPS connectino URI scheme and the application key that I have already created in the ThingWorx, which is bound to Administrator user 15. Once done press the back button on the screen to initiate the connection attempt 16. If all's set as it should be you will be able to see the Connected to Server option checked and the Property count for the Serial Number Property being updated every second For more detail on ThingWorx Android SDK refer to the ThingWorx Edge SDKs and WebScocket based Edge MicroServer (WS EMS) Help Center
View full tip
Scripto provides a RESTful endpoint for Groovy Custom Objects on the Axeda Platform.  Custom Objects exposed via Scripto can be accessed via a GET or a POST, and the script will have access to request parameters or body contents. Any Custom Object of the "Action" type will automatically be exposed via Scripto. The URL for a Scripto service is currently defined by the name of the Custom Object: GET: http://{{YourHostName}}/services/v1/rest/Scripto/execute/<customObjectName> Scripto enables the creation of "Domain Specific Services". This allows implementers to take the Axeda Domain Objects (Assets, Models, DataItems, Alarms) and expose them via a service that models the real-world domain directly (trucks, ATMs, MRI Machines, sensor readings). This is especially useful when creating a domain-specific UI, or when integrating with another application that will push or pull data. Authentication There are several ways to test your Scripto scripts, as well as several different authentication methods. The following authentication methods can be used: Request Parameter credentials: ?username=<yourUserName>&password=<yourPassword> Request Parameter sessionId (retrieved from the Auth service): ?sessionid=<sessionId> Basic Authentication (challenge): From a browser or CURL, simply browse to the URL to receive an HTTP Basic challenge. Request Parameters You can access the parameters to the Groovy script via two Objects, Call and Request. Request is actually just a sub-class of Call, so the values will always be the same regardless of which Object you use.  Although parameters may be accessed off of either object, Call is preferable when Chaining Custom Objects (TODO LINK) together.  Call also includes a reference to the logger which can be used to log debug messages. GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>?sessionid=<Session Id>&serial_number=mySerialNumber Accessing Parameters through the Request Object import com.axeda.drm.sdk.scripto.Request // Request.parameters is a map of strings def serial_number = Request.parameters.serial_number assert serial_number == "mySerialNumber"       Accessing Parameters through the Call Object import com.axeda.drm.sdk.customobject.Call // Call.parameters is a map of strings def serial_number = Call.parameters.serial_number assert serial_number == "mySerialNumber"       Accessing the POST Body through the Request Object The content from a POST request to Scripto is accessible as a string via the body field in the Request object.  Use Slurpers for XML or JSON to parse it into an object. POST:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>?sessionid=<Session Id> Response: { "serial_number":"mySerialNumber"} import com.axeda.drm.sdk.scripto.Request def body = Request.body def slurper = new JsonSlurper() def result = slurper.parseText(body) assert result.serial_number == "mySerialNumber"       Returning Plain Text Groovy custom objects must return some content.  The format of that content is flexible and can be returned as plain text, JSON, XML, or even binary files. The follow example simply returns plain text. GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name> // Outputs:  hello return ["Content-Type":"text/plain","Content":"hello"]       Returning JSON We use the JSONObject Class to format our Map-based content into a JSON structure. The eliminates the need for any concern around formatting, you just build up Maps of Maps and it will be properly formatted by the fromObject() utility method. GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name> import net.sf.json.JSONObject root = [   items:[    num_1: “one”,    num_2: “two”            ] ] /** Outputs {   "items": {  "num_1": "one", "num_2": "two"  } } **/ return ['Content-Type': 'application/json', 'Content': JSONObject.fromObject(root).toString(2)]       Link to JSONObject documentation Returning XML To return XML, we use the MarkupBuilder to build the XML response. This allows us to create code that follows the format of the XML that is being generated. GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>?sessionid=<Session Id> import groovy.xml.MarkupBuilder def writer = new StringWriter() def xml = new MarkupBuilder(writer) xml.root(){     items(){         num_1("one")         num_2("two")     } } /** Outputs <root>   <items>     <num_1>one</num_1>     <num_2>two</num_2>   </items> </root> **/ return ['Content-Type': 'text/xml', 'Content': writer.toString()]       Link to Groovy MarkupBuilder documentation Returning Binary Content To return binary content, you typically will use the fileStore API to upload a file that you can then download using Scripto.  See the fileInfo section to learn more. In this example we connect the InputStream which is associated with the getFileData() method directly to the output of the Scripto script. This will cause the bytes available in the stream to be directly forwarded to the client as the body of the response. GET:  http://{{Your Host Name}}/services/v1/rest/Scripto/execute/{{Your Script Name}}?sessionid={{Session Id}}&fileId=123 import static com.axeda.sdk.v2.dsl.Bridges.* import com.axeda.services.v2.* import com.axeda.sdk.v2.exception.* def contentType = parameters.type ?: 'image/jpg' return ['Content':fileInfoBridge.getFileData(parameters.fileId), 'Content-Type':contentType]   The Auth Service - Authentication via AJAX Groovy scripts are accessible to AJAX-powered HTML apps with Axeda instance credentials.  To obtain a session from an Axeda server, you should make a GET call to the Authentication service. The service is located at the following example URL: https://{{YourHostName}}/services/v1/rest/Auth/login This service accepts a valid username/password combination in the incoming Request parameters and returns a SessionID. The parameter names it expects to see are as follows: Property Name Description principal.username The username for the valid Axeda credential. password The password for the supplied credential. A sample request to the Auth Service: GET: https://{{YourHostName}}/services/v1/rest/Auth/login?principal.username=YOURUSER&password=YOURPASS Would yield this response (at this time the response is always in XML): <ns1:WSSessionInfo xsi:type="ns1:WSSessionInfo" xmlns:ns1="http://type.v1.webservices.sl.axeda.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">   <ns1:created>2013-08-12T13:19:37 +0000</ns1:created>   <ns1:expired>false</ns1:expired>   <ns1:sessionId>19c33190-dded-4655-b2c0-921528f7b873</ns1:sessionId> <ns1:sessionTimeout> 1800 </ns1:sessionTimeout> </ns1:WSSessionInfo>       The response fields are as follows: Field Name Description created The timestamp for the date the session was created expired A boolean indicating whether or not this session is expired (should be false) sessionId The ID of the session which you will use in subsequent requests sessionTimeout The time (in seconds) that this session will remain active for The Auth Service is frequently invoked from JavaScript as part of Custom Applications. The following code demonstrates this style of invocation. function authenticate(host, username, password) {             try {                 netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");             } catch (e) {                 // must be IE             }             var xmlHttpReq = false;             var self = this;             // Mozilla/Safari             if (window.XMLHttpRequest) {                 self.xmlHttpReq = new XMLHttpRequest();             }             // IE             else if (window.ActiveXObject) {                 self.xmlHttpReq = new ActiveXObject("Microsoft.XMLHTTP");             }             var SERVICES_PATH = "/services/v1/rest/"             var url = host + SERVICES_PATH + "Auth/login?principal.username=" + username + "&password=" + password;             self.xmlHttpReq.open('GET', url, true);             self.xmlHttpReq.onreadystatechange = function() {                 if (self.xmlHttpReq.readyState == 4) {                     getSessionId(self.xmlHttpReq.responseXML);                 }             }             self.xmlHttpReq.send() } function getSessionId(xml) {             var value             if (window.ActiveXObject) {                 // xml traversing with IE                 var objXML = new ActiveXObject("MSXML2.DOMDocument.6.0");                 objXML.async = false;                 var xmldoc = objXML.loadXML(xml);                 objXML.setProperty("SelectionNamespaces", "xmlns:ns1='http://type.v1.webservices.sl.axeda.com'");                 objXML.setProperty("SelectionLanguage","XPath");                 value =  objXML.selectSingleNode("//ns1:sessionId").childNodes[0].nodeValue;             } else {                 // xml traversing in non-IE browsers                 var node = xml.getElementsByTagNameNS("*", "sessionId")                 value = node[0].textContent             }             return value } authenticate ("http://mydomain.axeda.com", "myUsername", "myPassword")       Calling Scripto via AJAX Once you have obtained a session id through authentication via AJAX, you can use that session id in Scripto calls. The following is a utility function which is frequently used to wrap Scripto invocations from a UI. function callScripto(host, scriptName, sessionId, parameter) {             try {                 netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");             } catch (e) {                 // must be IE             }             var xmlHttpReq = false;             var self = this;             // Mozilla/Safari             if (window.XMLHttpRequest) {                 self.xmlHttpReq = new XMLHttpRequest();             }             // IE             else if (window.ActiveXObject) {                 self.xmlHttpReq = new ActiveXObject("Microsoft.XMLHTTP");             }             var url = host + SERVICES_PATH + "Scripto/execute/" + scriptName + "?sessionid=" + sessionId;             self.xmlHttpReq.open('GET', url, true);             self.xmlHttpReq.onreadystatechange = function() {                 if (self.xmlHttpReq.readyState == 4) {                     updatepage(div, self.xmlHttpReq.responseText);                 }             }             self.xmlHttpReq.send(parameter); } function updatepage(div, str) {             document.getElementById(div).innerHTML = str; } callScripto("http://mydomain.axeda.com", "myGroovyScriptName", "mySessionId", "myparameter=foo")       A more modern jQuery-based example might look like the following: function callScripto(host, scriptName, sessionId, parameter) {     var url = host + '/services/v1/rest/Scripto/execute/' + scriptName + '?sessionid=' + sessionId     if ( parameter != null ) url += '&' + parameter     $.ajax({url: url,               success:  function(response) {  updatepage(div, response); }           }); } function updatepage(div, str) {     $("#" + div).innerHTML = str } callScripto("http://mydomain.axeda.com", "myGroovyScriptName", "mySessionId", "myparameter=foo") In Conclusion As shown above, Scripto offers a number of ways to interact with the platform.  On each version of the Axeda Platform, all supported v1 and v2 APIs are available for Scripto to interact with the Axeda domain objects and implement business logic to solve real-world customer problems. Bibliography ​(PTC.net account required)     Axeda v2 API/Services Developer's Reference Version 6.8.3 August 2015     Axeda® v1 API Developer’s Reference Guide Version 6.8 August 2014     Documentation Map for Axeda® 6.8.2 January 2015
View full tip
    Automate business processes with Services, Events and Subscriptions.   Guide Concept   This project will introduce Services, Events, and Subscriptions inside of the ThingWorx platform. Following the steps in this guide, you will be able to expand your data model using Services, Events, and Subscriptions.   We will teach you how to make a more robust and enjoyable experience for users simply by using the resources inside of the ThingWorx Composer.   You'll learn how to   Create Events, Services and Subscriptions in Composer Utilize the ThingWorx Edge SDK platforms with Services, Subscriptions, and Events   NOTE:  The estimated time to complete this guide is 60 minutes     Step 1: Completed Example   This guide references the attached EventsServicesSubscription.zip. The sample application is based on a company needing to make deliveries. The rules engine will handle much of the work outside of the transportation workflow.   Unzip and 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.   What's Inside    Name                                            Type PTCDelivers Thing PTCDeliversBusinessLogic Thing PackageStream Stream OrdersDatabase Database DeliveryDataTable Database PackageDataTable Database MerchantDatabase Database PlaneThingTemplate ThingTemplate MerchantThingTemplate ThingTemplate TruckThingTemplate ThiingTemplate ClientThingShape ThingShape VehicleDeliveryShape ThingShape PackageDataShape DataShape CustomerDataShape DataShape OrderDataShape DataShape PackageDeliveryDataShape DataShape MerchantOrderDataShape DataShape MerchantDataShape DataShape default_user User TestDashboardMashup1 Mashup TestGadget Mashup     Step 2: Functionality   You can combine Services, Subscriptions, and Events to automate business processes or trigger notifications. See the definitions and examples before to gain a better understanding as to the role each plays.    Name                 Function Services Methods and functions to be used within a ThingWorx application. There are Services provided by the system, but custom services need to be made to create the application's functional requirements. All services in the ThingWorx Composer can be accessed by a user with the appropriate permissions. Remote services can be created with the use of the ThingWorx SDKs. Events An Event represent a change in state of a property or changes in a running application. Changes can be handled in different ways based on the method used to fire or queue them. They are a great resource for property value changes and alerts. Subscriptions The implementation for a subscription is the same as that of a service. Subscriptions are activated when the Event they are listened for is triggered.       Step 3: Create Events   Events are used to mark situations that can occur within an application. They can be used for scenarios ranging from a dangerous situation that is imminent and needs to be checked by personnel to just a system notification. Each Event is based on a DataShape that will hold the necessary information about the Event.   For example, it wouldn’t be enough to just know that a rain Event has occurred. It might be helpful to also know the location, the time the rain started and expectations of the amount of rain to fall.   Follow the steps below to create an Event for the TruckThingTemplate Entity.   Open the TruckThingTemplate Entity and click the Events tab. Click Add.   Enter an Event name, such as PackageDelivered. For the DataShape, in the Search Data Shape field, filter and select PackageDataShape.   Events can be queued or fired based on updates done in Composer, property changes of a running application, or programmatically. Triggering or firing an Event can be done in Services utilizing JavaScript.       Step 4: Services Interface   To create Services within ThingWorx, go to the Services tab of the Entity that will house the Service. Our PTCDeliversBusinessLogic Thing will contain several Services for us.   Within the Services tab under the Entity Information section of a Thing, you will see built in functionality for all the ThingTemplates and ThingShapes the Thing inherits from. You will also see the section that allows you to create new Services.   Service Info Tab   This tab is for the general information of the Service. This is where you will add the Service name, description, category, whether the service is asynchronous, and whether the Service can be overridden.     Inputs Tab   This tab is for the parameters for the Service. For input parameters, a parameter can be required and default values are allowed.     Outputs Tab   This tab is for the return type of the Service. The resulting output of the Service can stretch from being nothing to user defined Entities.     Snippets Tab   This tab allows users to pick from reusable JavaScript code that is specific to ThingWorx. These snippets are grouped by resources used, functionality, and type. You are also provided a search bar to look for keywords or titles.   When a snippet is found, click the arrow. This will insert the JavaScript code into the Script section wherever the cursor is located. From here, edit the inserted snippet to work with the rest of your code. This section is often helpful in getting to know how to perform service calls and code for the ThingWorx environment.     Me/Entities Tab   A listing of all Properties, Events, and Services belonging to custom and provided Entities in ThingWorx. As with the Snippets section, clicking the blue and white arrow will insert the reusable code to wherever the cursor is located. After the code is inserted, update the code to your liking. This is often a great resource for buildiung up payload for Service calls.       Click here to view Part 2 of this guide.
View full tip
In this blog I will be inspecting the setup below, using the REST APIs exposed by the different components (log-analysis-free guaranteed).   The components are started in stages, and I will do some exploration between each stages : EMS only EMS + LSR 1 EMS + LSR 1 + LSR 2    The REST APIs   Edge MicroServer (EMS) REST API This API is very similar to the ThingWorx platform REST API, see REST APIs Supported by WS EMS for specificity. I will be monitoring the EMS using the LocalEms virtual Thing (EMS only) ThingWorx Platform REST API This is the well known ThingWorx Core REST API -  see REST API Core Concepts I will be monitoring the EMS, from the platform, using an EMSGateway thing. The EMSGateway exposes on the platform some of the LocalEms services (like GetEdgeThings). I'm also inspecting the remote properties / services / events exposed on the things using the RemoteThing::GetRemoteMetadata service. Lua Script Resource (LSR) REST API This API largely differs from the ones above, the API documentation is served by the LSR itself (e.g. http://localhost:8001/)   I will use it to list the scripts loaded by the LSR process.  Configuration   See above diagram - Platform is listening on port 8084, no encryption, EMS and LSRs on the same host...   Platform configuration : for each edge thing, a corresponding remote thing was manually created on the platform EMSGateway1 as a EMSGateway Thing Template EMSOnlyThing as a RemoteThingWithFileTransfer LUAThing2 as a RemoteThing LUAThing1 as a RemoteThing LUAOnlyThing as a RemoteThing   EMS configuration : /etc/config.json - listening on default port 8000   {     "ws_servers": [{             "host": "tws74neo",             "port": 8084         }     ],     "appKey": "xxxxxx-5417-4248-bc01-yyyyyyy",     "logger": {         "level": "TRACE"     },     "ws_connection": {         "encryption": "none"     },     "auto_bind": [{             "name": "EMSGateway1",             "gateway": true         }, {             "name": "EMSOnlyThing",             "gateway": false         }, {             "name": "LUAThing2",             "host": "localhost",             "port": 8002,             "gateway": false         }, {             "name": "LUAThing1",             "gateway": false         }     ],     "file": {         "virtual_dirs": [{                 "emsrepository": "E:\\ptc\\ThingWorx\\EMS-5-3-2\\repositories\\data"             }         ],         "staging_dir": "E:\\ptc\\ThingWorx\\EMS-5-3-2\\repositories\\staging"     } } LSR process (1) : /etc/config.lua - listening on default port 8001 (using the out of the box sample Lua scripts)   scripts.log_level = "INFO"   scripts.LUAThing1 = {     file = "thing.lua",     template = "example", }   scripts.sample = {   file = "sample.lua" } LSR process (2) : /etc/config2.lua - listening on port 8002 (using the out of the box sample Lua scripts) This LSR process is started with command "luaScriptResource.exe -cfg .\etc\config2.lua"   scripts.log_level = "INFO" scripts.script_resource_port = 8002 scripts.LUAThing2 = {     file = "thing.lua",     template = "example", }   scripts.LUAOnlyThing = {     file = "thing.lua",     template = "example", }   Stage 1 : EMS only     ThingWorx REST API   Request: Call the GetEdgeThings service on the EMSGateway1 thing POST  twx74neo:8084/Thingworx/Things/EMSGateway1/Services/GetEdgeThings Response: As expected, only the remote things flagged as auto_bind are listed   name host port path keepalive timeout proto user accept EMSGateway1   8001.0 / 60000.0 30000.0 http   application/json EMSOnlyThing   8001.0 / 60000.0 30000.0 http   application/json LUAThing1   8001.0 / 60000.0 30000.0 http   application/json LUAThing2 localhost 8002.0 / 60000.0 30000.0 http   application/json                                                               Request: Call the GetRemoteMetadata service on the LUAThing1 thing POST  twx74neo:8084/Thingworx/Things/LUAThing1/Services/GetRemoteMetadata Response: As expected, remote properties / services and events are not available since the LSR associated with this thing is off.   Unable to Invoke Service GetRemoteMetadata on LUAThing1 : null   EMS REST API   Request: Call the GetEdgeThings service on the LocalEms virtual thing POST  localhost:8000/Thingworx/Things/LocalEms/Services/GetEdgeThings Response: output is identical to the gateway thing on the platform   { "name": "EMSGateway1", "host": "", "port": 8001, "path": "/",  "keepalive": 60000, "timeout": 30000, "proto": "http", "user": "", "accept": "application/json" }, { "name": "EMSOnlyThing", "host": "", "port": 8001, "path": "/", "keepalive": 60000, "timeout": 30000, "proto": "http", "user": "", "accept": "application/json" }, { "name": "LUAThing1", "host": "", "port": 8001, "path": "/", "keepalive": 60000, "timeout": 30000, "proto": "http", "user": "", "accept": "application/json" }, { "name": "LUAThing2", "host": "localhost", "port": 8002, "path": "/", "keepalive": 60000, "timeout": 30000, "proto": "http", "user": "", "accept": "application/json"}            LSR REST API N/A - no LSR process started yet.   Stage 2 : EMS + LSR 1 (8001)     ThingWorx REST API   Request: Call the GetEdgeThings service on the EMSGateway1 thing POST  twx74neo:8084/Thingworx/Things/EMSGateway1/Services/GetEdgeThings Response: LUAThing1 is associated to an LUA script   name host port path keepalive timeout proto user accept EMSGateway1   8001.0 / 60000.0 30000.0 http   application/json EMSOnlyThing   8001.0 / 60000.0 30000.0 http   application/json LUAThing1 localhost 8001.0 /scripts/Thingworx 60000.0 15000.0 http   application/json LUAThing2 localhost 8002.0 / 60000.0 30000.0 http   application/json   Request: Call the GetRemoteMetadata service on the LUAThing1 thing POST  twx74neo:8084/Thingworx/Things/LUAThing1/Services/GetRemoteMetadata Response: Now that the Lua script for LUAThing1 is running, remote properties / services and events are available   {"isSystemObject":false,"propertyDefinitions":{"Script_Pushed_Datetime":{"sourceType":"ThingShape","aspects":{"isReadOnly":false,"dataChangeThreshold":0,"defaultValue":1495619610000,"isPersistent":false,"pushThreshold":0,"dataChangeType":"VALUE","cacheTime":0,"pushType":"ALWAYS"},"name":"Script_Pushed_Datetime","description":"","category":"","tags":[],"baseType":"DATETIME","ordinal":0},"Pushed_InMemory_Boolean":{"sourceType":"ThingShape","aspects":....   EMS REST API      LocalEms::GetEdgeThings returns same output as EMSGateway::GetEdgeThings   LSR REST API (port 8001)   Request: List all the scripts running in the first LSR GET  localhost:8001/scripts?format=text/html Response: We find our sample script and the script associated with LUAThing1 (the Thingworx script is part of the infrastructure and always there)   Name Status Result File LUAThing1 Running   E:\ptc\ThingWorx\EMS-5-3-2\etc\thingworx\scripts\thing.lua sample Running   sample.lua Thingworx Running   E:\ptc\ThingWorx\EMS-5-3-2\etc\thingworx\scripts\thingworx.lu   Stage 3 : EMS + LSR 1 (8001) + LSR 2 (8002)     ThingWorx REST API   Request: Call the GetEdgeThings service on the EMSGateway1 thing POST  twx74neo:8084/Thingworx/Things/EMSGateway1/Services/GetEdgeThings Response: LUAOnlyThing is now listed and LUAThing2 is associated with a LUA script   name host port path keepalive timeout proto user accept EMSGateway1   8001.0 / 60000.0 30000.0 http   application/json EMSOnlyThing   8001.0 / 60000.0 30000.0 http   application/json LUAOnlyThing localhost 8002.0 /scripts/Thingworx 60000.0 15000.0 http   application/json LUAThing1 localhost 8001.0 /scripts/Thingworx 60000.0 15000.0 http   application/json LUAThing2 localhost 8002.0 /scripts/Thingworx 60000.0 15000.0 http   application/json   EMS REST API      LocalEms::GetEdgeThings returns same output as  EMSGateway::GetEdgeThings   LSR REST API (port 8002)   Request: List all the scripts running in the second LSR GET  localhost:8002/scripts?format=text/html Response: Returns the status of all the scripts currently loaded   Name Status Result File LUAOnlyThing Running   .\etc\thingworx\scripts\thing.lua LUAThing2 Running   .\etc\thingworx\scripts\thing.lua Thingworx Running   .\etc\thingworx\scripts\thingworx.lua
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
Build, customize, and deploy IoT applications with ThingWorx.   NOTE: Complete the following guides in sequential order. The estimated time to complete this learning path is 270 minutes.   1. Create Your Application UI  Part 1 Part 2 Part 3 Part 4 Part 5 2. Basic Mashup Widgets  Part 1 Part 2 Part 3 3. Define Your UI Style  Part 1 Part 2 4. Object-Oriented UI Design Tips 5. Deploy an Application 6. How to Display Data in Charts  Part 1 Part 2 Part 3
View full tip
Dive back into the mashup builder and learn about advanced widgets and layout options.   For full-sized viewing, click on the YouTube link in the player controls.   Visit the Online Success Guide to access our Expert Session videos at any time as well as additional information about ThingWorx training and services.
View full tip
In this video we cover the installation of the UploadThing module. This video applies to ThingWorx Analytics 52.2 till 8.0. This is no longer applicable with ThingWorx Analytics 8.1   Useful links: How to copy files from Windows to Linux Updated Link for access to this video:  Installing Thingworx Analytics Builder: Part 3 of 3  
View full tip
Configure Permissions Guide Part 2   Step 5: Permissions   These permissions can be accessed on any Entity created on the platform. All Entities have permission control for both design time and run time. Permission Time Control Design time Controls what Users are able to do with Entities themselves while building the solution. Run time Controls what the Users are able to do with the data for an Entity when they use the solution.   Permission Type Description Property Read Read property values Property Write Update property values Service Execute Execute Services in this Entity Event Execute Queue or fire Events in this Entity Event Subscribe Ability to subscribe to Events in this Entity   Access Type Description Allow Allow the User's access to this feature. Deny Deny the User's access to this feature. Inherit Set the User's access to this feature based on permissions in Entities this Entity is based on or the configurations at a higher level.   Add Permissions for an Entity   Once an Entity has been selected for editing, select the Permissions tab. Based on what you would like to edit, select the Visibility, Design Time or Run Time tab. The All Properties, Services, and Events section provides blanket security to all of these features for a User Group or User. The Property, Service, or Event Overrides section is used for any overrides that need to be made for specific features. In the example blow, the User a.jones has the ability to read properties, fire events, and subscribe to events. The User does not have the ability to update a property or execute a Service. In the second section, a.jones is allowed to call the GetConfigurationTable Service (even though he was restricted from doing so in the other section).   To set a permission, filter and select a User/User Group. When their name is in the table, click the Permission Type you would like for this Entity. Default permissions are added to the User or User Group you filtered and selected. This will be full access permissions unless you've changed one of the fields.   Set Permissions Programmatically   In some cases it will be useful to set permissions using a programmable interface. This can be done through a built-in set of services which can be accessed in many different ways including: Internal service call through an entity’s service Service call using the extension framework, or REST API call to a service on the platform. The following is a list of services built into all entities on the platform. Service Name Description AddDesignTimePermission Adds a new design time permission AddRunTimePermission Adds a new run time permission CheckDesignTimePermission Checks to see if an entity has a specific design time permission for the current User CheckDesignTimePermissionForGroup Checks to see if an entity has a specific design time permission for a given User Group CheckDesignTimePermissionForUser Checks to see if an entity has a specific design time permission for a given User CheckPermission Checks to see if the entity has a specific run time permission for the current User CheckTimePermissionForGroup Checks to see if the entity has a specific run time permission for a given User Group CheckDesignTimePermissionForUser Checks to see if the entity has a specific run time permission for a given User DeleteDesignTimePermission Delete a design time permission DeleteRunTimePermission Delete a run time permission GetDesignTimePermission Get a list of design time permissions in Info Table format GetDesignTimePermissionAsJSON Get a list of design time permissions in JSON format GetPermissionsForCurrentUser Get the run time permissions for the current User GetPermissionsForGroup Get the run time permissions for a given User Group GetPermissionsForUser Get the run time permissions for a given User GetRunTimePermissions Get a list of assigned run time permissions in Info Table format GetRunTimePermissionAsJSON Get a list of assigned run time permissions in JSON form SetDesignTimePermissionAsJSON Sets all of the run time permissions for a given Entity to the given JSON list You may want to apply a set of permissions to a large group of Entities at once. This can be done using either the projects or the tags feature on the platform through the EntityServices resource. The EntityServices resource has many useful services in it, but for the purpose of this section, we will only talk about the run time permission service. This will act on all entities with the provided tags or assigned to the given project. Service Name Description SetEntityPermission Sets run time permissions for a set of Entities   Step 6: Application Keys   Application Keys   Application Keys or appKeys are security tokens used for authentication in ThingWorx when not using a standard credentials method of authentication. They are associated with a given user and have all of the permissions granted to the user to which they are associated.   Create an Application Key   Using the Application Key for the default user (Administrator) is not recommended. If administrative access is absolutely necessary, create a user and place the user as a member of the SecurityAdministrators and Administrators user groups. Create the User the Application Key will be assigned to. On the Home screen of Composer click + New. In the dropdown list, click Applications Keys. Use MyAppKey  for the name your Application Key. Set the User Name Reference to a User you created and set the Project field (ie, PTCDefaultProject). The Expiration Date field will default to 1 day. Click Save. A Key ID has been generated and can be used to make secure connections.   IP Whitelisting for Application Keys   One of the features of an Application Key is the ability to set an IP whitelist. This allows the server to specify that only certain IP addresses should be able to use a given Key ID for access. This is a great way to lock down security on the platform for anything that will maintain a static IP address. For example, connected Web-based business systems may have a static IP from which all calls should be made. Similarly, you can use wildcards to specify a network to narrow the range of IP addresses allowed while still offering some flexibility for devices with dynamic IP addresses. Extremely mobile devices should likely not attempt to implement this however as they will often change networks and IP addresses and may lose the ability to connect when the IP whitelist feature is used.   Interact with Application Keys Programmatically   Service Name Description GetKeyID Returns the ID of this application key GetUserName Get the user name associated with this application key IsExpired Returns if this application key is expired ResetExpirationDateToDefault Resets the expiration date of the application key to the default time based on configuration in the UserManagement subsystem SetClientName Sets the client name for this application key SetExpirationDate Sets the expiration date of this application key to a provided date SetIPWhiteList Sets the values for the IP whitelist for this application key SetUserName Sets the associated user name for this application key TIP: To learn more about Application Keys, refer to the Create an Application Key Guide.   Step 7: Organizations   Organizations are hierarchical structures that allow the user to assign visibility to entities in the ThingWorx Model. This model provides the top down structure from the highest level in an organization or department, to the lower levels of said entity. Each level within this structure also allows for users and groups to be added. This provides a greater level of customization to resources within the ThingWorx Composer.   Create an Organization In the ThingWorx Composer, click the + New at the top of the screen. Select Organization in the dropdown. Name your Organization Constructors. Set the Project field (ie, PTCDefaultProject) and click Save Select the Organization tab to see the hierarchy. With the top organization selected, in the Members search bar, search for the user you have created yourself and add them.   Create Organizational Units   Click the green + under the structure you would like to expand. Name your Organization unit UpperManagement. In the Members search bar, search for the user or user group you created and add it. Click Save. Repeat the steps to create the full heirarchy of the organization and its department/unit members.   Setup Entity Visibility   ThingWorx provides added security checks and access control with Entity visibility. Visibility ensures an entity is accessible to members of an organizational unit. Those members will then have access to the entity and the underlying security model determines what specific interaction any users that are members of that organization unit may have with a specific asset. If a user in the system is not granted visibility, then that asset essentially does not exist within that user’s domain. Select the Permissions tab of any custom Thing in Composer. Filter and select Constructors in the Search Organizations field. Click Save. Login Pages for Organization   Creating an Organization automatically creates a login page for you. If you would like to add more to this login screen and customize it to fit your needs, create a Mashup and set it to the Organization's Home Mashup field. If you plan to use a Login Screen, use the View Mashup URL generated from the Login Mashup you create. To view the login page of your application (whether custom or default), type the following URL: [server]/Thingworx/FormLogin/ (ie, localhost/Thingworx/FormLogin/Constructors).     Step 8: Next Steps   Congratulations! You've successfully completed the Configure Permissions guide, and learned how to: Configure and utilize the user access system Control permissions at design time and run time   The next guide in the Getting Started on the ThingWorx Platform learning path is Build a Predictive Analytics Model.    If you are completing the Connect and Configure Industrial Devices and Systems learning path, the next guide is Choose a Connectivity Method.   Learn More   We recommend the following resources to continue your learning experience: Capability Guide Build Design Your Data Model   Additional Resources   If you have questions, issues, or need additional information, refer to: Resource Link Support Help Center    
View full tip
Announcements