IoT Tips

import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.device.ModelFinder import com.axeda.drm.sdk.device.Model import com.axeda.drm.sdk.device.DeviceFinder import com.axeda.drm.sdk.data.CurrentDataFinder import com.axeda.drm.sdk.device.Device import com.axeda.drm.sdk.data.HistoricalDataFinder import net.sf.json.JSONObject /* * DataItemEachDevice.groovy * * Find the current data item and historical data items for all assets in a given model. * * @param model_name - (REQ):Str name of the model. * @param data_item_name - (REQ):Str name of the data item to query on. * @param from_time - (REQ):Long millisecond timestamp to begin query from. * @param to_time - (REQ):Long millisecond timestamp to end query at. * * @note from_time and to_time should be provided because it limits the query size. * * @author Sara Streeter <sstreeter@axeda.com> */ def response = [:] // measure the script run time def timeProfiles = [:] def scriptStartTime = new Date() try { // getUserContext is supported as of release 6.1.5 and higher final def CONTEXT = Context.getUserContext() // confirm that required parameters have been provided validateParameters(actual: parameters, expected: ["model_name", "data_item_name", "from_time", "to_time"]) // find the model def modelFinder = new ModelFinder(CONTEXT) modelFinder.setName(parameters.model_name) Model model = modelFinder.findOne() // throw exception if no model found if (!model) { throw new Exception("No model found for ${parameters.model_name}.") } // find all assets of that model def assetFinder = new DeviceFinder(CONTEXT) assetFinder.setModel(model) def assets = assetFinder.findAll() // find the current and historical data values for each asset //note: since device will be set on the datafinders going forward, a dummy device is set on instantiation which is not actually stored def currentDataFinder = new CurrentDataFinder(CONTEXT, new Device(CONTEXT, "placeholder", model)) def historicalDataFinder = new HistoricalDataFinder(CONTEXT, new Device(CONTEXT, "placeholder", model)) historicalDataFinder.startDate = new Date(parameters.from_time as Long) historicalDataFinder.endDate = new Date(parameters.to_time as Long) // assemble the response assets = assets.collect { Device asset -> currentDataFinder.device = asset def currentValue = currentDataFinder.find(parameters.data_item_name) historicalDataFinder.device = asset def valueList = historicalDataFinder.find(currentValue?.dataItem) [ id: asset.id.value, name: asset.name, serialNumber: asset.serialNumber, model: [id: asset.model.id.value, name: asset.model.name], current_data: currentValue.asString(), historical_data: valueList.collect { [timestamp: it.getTimestamp().format("yyyyMMdd HH:mm"), value: it.asString()] } ] } response = [result: [items: assets]] } catch (def ex) { logger.error ex response += [ error: [ type: "Backend Application Error", msg: ex.getLocalizedMessage() ] ] } finally { // create and output the running time profile timeProfiles << createTimeProfile("DataItemEachDevice", scriptStartTime, new Date()) response += [params: parameters, meta: [:], timeProfiles: timeProfiles] } return ['Content-Type': 'application/json', 'Content': JSONObject.fromObject(response).toString(2)] private Map createTimeProfile(String label, Date startTime, Date endTime) { [ (label): [ startTime: [timestamp: startTime.time, readable: startTime.toString()], endTime: [timestamp: endTime.time, readable: endTime.toString()], profile: [ elapsed_millis: endTime.time - startTime.time, elapsed_secs: (endTime.time - startTime.time) / 1000 ] ] ] } private validateParameters(Map args) { if (!args.containsKey("actual")) { throw new Exception("validateParameters(args) requires 'actual' key.") } if (!args.containsKey("expected")) { throw new Exception("validateParameters(args) requires 'expected' key.") } def config = [ require_username: false ] Map actualParameters = args.actual.clone() as Map List expectedParameters = args.expected config.each { key, value -> if (args.options?.containsKey(key)) { config[key] = args.options[key] } } if (!config.require_username) { actualParameters.remove("username") } expectedParameters.each { paramName -> if (!actualParameters.containsKey(paramName) || !actualParameters[paramName]) { throw new IllegalArgumentException( "Parameter '${paramName}' was not found in the query; '${paramName}' is a reqd. parameter.") } } } Sample Output: { "result": { "items": [{ "id": 4240, "name": "ASVM_9", "serialNumber": "ASVM_9", "model": { "id": 1535, "name": "SimVM4" }, "current_data": "142.0", "historical_data": [{ "timestamp": "20120331 17:00", "value": "142.0" }, { "timestamp": "20120331 16:59", "value": "143.0" }, { "timestamp": "20120331 16:59", "value": "144.0" }, { "timestamp": "20120331 16:58", "value": "145.0" }, { "timestamp": "20120331 16:58", "value": "146.0" }, { "timestamp": "20120331 16:57", "value": "147.0" }, { "timestamp": "20120331 16:57", "value": "148.0" }, { "timestamp": "20120330 19:30", "value": "0.0" }] }, { "id": 4246, "name": "ASVM_12", "serialNumber": "ASVM_12", "model": { "id": 1535, "name": "SimVM4" }, "current_data": "138.0", "historical_data": [{ "timestamp": "20120331 17:00", "value": "138.0" }, { "timestamp": "20120331 17:00", "value": "139.0" }, { "timestamp": "20120331 16:59", "value": "140.0" }, { "timestamp": "20120331 16:59", "value": "141.0" }, { "timestamp": "20120331 16:59", "value": "142.0" }, { "timestamp": "20120331 16:59", "value": "143.0" }, { "timestamp": "20120330 19:32", "value": "0.0" }] // // MORE ASSETS HERE // }] }, "params": { "username": "sstreeter", "from_time": "1332272219000", "data_item_name": "CurrentStock", "sessionid": "JOQ5I7ofRXYA-RnA37Vk93bRUH718yoFF5 9p0JbCnfyoHolFprf", "model_name": "SimVM4", "to_time": "1335469008000" }, "meta": {}, "timeProfiles": { "DataItemEachDevice": { "startTime": { "timestamp": 1335469168725, "readable": "Thu Apr 26 19:39:28 GMT 2012" }, "endTime": { "timestamp": 1335469180569, "readable": "Thu Apr 26 19:39:40 GMT 2012" }, "profile": { "elapsed_millis": 11844, "elapsed_secs": 11.844 } } } }

May 25, 2016

Email an attachment using bytes from a FileInfo Parameters: fileId - the identifier to a FileInfo that has been previously uploaded to the FileStore filename - the name of the attachment toaddress - the email address to send to fromaddress - the email address to send from import com.axeda.drm.util.Emailer; import com.axeda.drm.sdk.contact.Email import javax.mail.internet.AddressException; import javax.mail.internet.InternetAddress; import static com.axeda.sdk.v2.dsl.Bridges.* import com.axeda.services.v2.FileInfoCriteria import org.apache.commons.io.IOUtils import java.security.MessageDigest try { String fromaddress = parameters.fromaddress String toaddress = parameters.toaddress def fileId = parameters.fileId def filename = parameters.filename String subject = "Axeda Test Attachment" String body = "<html><head/><body><p style='background:blue;'>This email has an attachment and a blue background.</p></body></html>" def thefile = new File(filename) def inputStream = fileInfoBridge.getFileData(fileId) byte[] bytes = IOUtils.toByteArray(inputStream); thefile.setBytes(bytes) def random_hash = md5('r'); def contentType = "multipart/mixed; boundary=--\"$random_hash\"\r\n" def htmlType = "text/html" sendEmail(fromaddress, toaddress, subject, body, contentType, thefile, false, htmlType) } catch (Exception e) { logger.error(e.localizedMessage) } return true def md5(String s) { MessageDigest digest = MessageDigest.getInstance("MD5") digest.update(s.bytes); new BigInteger(1, digest.digest()).toString(16).padLeft(32, '0') } public void sendEmail(String fromAddress, String toAddress,String subject, String body, String encoding, File file, boolean compress, String mimeType) { try { Emailer.getInstance().send([new InternetAddress(toAddress)],new InternetAddress(fromAddress), subject,body, encoding, [file] as File[], compress, mimeType); } catch (Exception ae) { logger.error(ae.localizedMessage); } }

May 25, 2016

This tutorial applies to Axeda version 6.1.6+, with sections applicable to 6.5+ (indicated below) Custom objects (or Groovy scripts) are the backbone of Axeda custom applications. As the developer, you decide what content type to give the data returned by the script. What this tutorial covers? This tutorial provides examples of outputting data in different formats from Groovy scripts and consuming that data via Javascript using the jQuery framework. While Javascript and jQuery are preferred by the Axeda Innovation team, any front end technology that can consume web services can be used to build applications on the Axeda Machine Cloud. On the same note, the formats discussed in this article are only a few examples of the wide variety of content types that Groovy scripts can output via Scripto. The content types available via Scripto are limited only by their portability over the TCP protocol, a qualification which includes all text-based and downloadable binary mime types. As of July 2013, the UDP protocol (content streaming) is not supported by the current version of the Axeda Platform. Formats discussed in this article: 1) JSON 2) XML 3) CSV 4) Binary content with an emphasis on image files (6.5+) For a tutorial on how to create custom objects that work with custom applications, check out Using Google Charts API with Scripto. For a discussion of what Scripto is and how it relates to Groovy scripts and Axeda web services, take a look at Unleashing the Power of the Axeda Platform via Scripto. Serializing Data JSON For those building custom applications with Javascript, serializing data from scripts into JSON is a great choice, as the data is easily consumable as native Javascript objects. The net.sf.json JSON library is available to use in the SDK. It offers an easy way to serialize objects on the Platform, particularly v2 SDK objects. import net.sf.json.JSONArray import static com.axeda.sdk.v2.dsl.Bridges.* def asset = assetBridge.findById(parameters.assetId) def response = JSONArray.fromObject(asset).toString(2) return ["Content-Type": "application/json", "Content": response] Outputs: [{ "buildVersion": "", "condition": { "detail": "", "id": "3", "label": "", "restUrl": "", "systemId": "3" }, "customer": { "detail": "", "id": "2", "label": "Default Organization", "restUrl": "", "systemId": "2" }, "dateRegistered": { "date": 11, "day": 1, "hours": 18, "minutes": 7, "month": 2, "seconds": 49, "time": 1363025269253, "timezoneOffset": 0, "year": 113 }, "description": "", "detail": "testasset", "details": null, "gateways": [], "id": "12345", "label": "", "location": { "detail": "Default Organization", "id": "2", "label": "Default Location", "restUrl": "", "systemId": "2" }, "model": { "detail": "testmodel", "id": "2345", "label": "standalone", "restUrl": "", "systemId": "2345" }, "name": "testasset", "pingRate": 0, "properties": [ { "detail": "", "id": "1", "label": "TestProperty", "name": "TestProperty", "parentId": "2345", "restUrl": "", "systemId": "1", "value": "" }, { "detail": "", "id": "4", "label": "TestProperty0", "name": "TestProperty0", "parentId": "2345", "restUrl": "", "systemId": "4", "value": "" }, { "detail": "", "id": "3", "label": "TestProperty1", "name": "TestProperty1", "parentId": "2345", "restUrl": "", "systemId": "3", "value": "" }, { "detail": "", "id": "2", "label": "TestProperty2", "name": "TestProperty2", "parentId": "2345", "restUrl": "", "systemId": "2", "value": "" } ], "restUrl": "", "serialNumber": "testasset", "sharedKey": [], "systemId": "12345", "timeZone": "GMT" }] This output can be traversed as Javascript object with its nodes accessible using dot (.) notation. For example, if you set the above JSON as the content of variable "json", you can access it in the following way, without any preliminary parsing needed: assert json[0].condition.id == 3 If you use jQuery, a Javascript library, feel free to make use of axeda.js, which contains utility functions to pass data to and from the Axeda Platform. One function in particular is used in most example custom applications found on this site, the axeda.callScripto function. It relies on the jQuery ajax function to make the underlying call. /** * makes a call to the enterprise platform services with the name of a script and passes * the script any parameters provided. * * default is GET if the method is unknown * * Notes: Added POST semantics - plombardi @ 2011-09-07 * * original author: Zack Klink & Philip Lombardi * added on: 2011/7/23 */ // options - localstoreoff: "yes" for no local storage, contentType: "application/json; charset=utf-8", axeda.callScripto = function (method, scriptName, scriptParams, attempts, callback, options) { var reqUrl = axeda.host + SERVICES_PATH + 'Scripto/execute/' + scriptName + '?sessionid=' + SESSION_ID var contentType = options.contentType ? options.contentType : "application/json; charset=utf-8" var local var daystring = keygen() if (options.localstoreoff == null) { if (localStorage) { local = localStorage.getItem(scriptName + JSON.stringify(scriptParams)) } if (local != null && local == daystring) { return dfdgen(reqUrl + JSON.stringify(scriptParams)) } else { localStorage.setItem(scriptName + JSON.stringify(scriptParams), daystring) } } return $.ajax({ type: method, url: reqUrl, data: scriptParams, contentType: contentType, dataType: "text", error: function () { if (attempts) { expiredSessionLogin(); setTimeout(function () { axeda.callScripto('POST', scriptName, scriptParams, attempts - 1, callback, options) }, 1500); } }, success: function (data) { if (options.localstoreoff == null) { localStorage.setItem(reqUrl + JSON.stringify(scriptParams), JSON.stringify([data])) } if (contentType.match("json")) { callback(unwrapResponse(data)) } else { callback(data) } } }) }; Using the axeda.callScripto function: var postToPlatform = function (scriptname, callback, map) { var options = { localstoreoff: "yes", contentType: "application/json; charset=utf-8" } // Javascript object "map" has to be stringified to post to Axeda Platform axeda.callScripto("POST", scriptname, JSON.stringify(map), 2, function (json) { // callback gets the JSON object output by the Groovy script callback(json) }, options) } The JSON object is discussed in more detail here. Back to Top XML XML is the preferred language of integration with external applications and services. Groovy provides utilities to make XML serialization a trivial exercise. import groovy.xml.MarkupBuilder import static com.axeda.sdk.v2.dsl.Bridges.* def writer = new StringWriter() def xml = new MarkupBuilder(writer) def findAssetResult = assetBridge.find(new AssetCriteria(modelNumber: parameters.modelName)) // find operation returns AssetReference class. Contains asset id only def assets = findAssetResult.assets xml.Response() { Assets() { assets.each { AssetReference assetRef -> def asset = assetBridge.findById(assetRef.id) // asset contains a ModelReference object instead of a Model. ModelReference has a detail property, not a name property Asset() { id(asset.id) name(asset.name) serial_number(asset.serialNumber) model_id(asset.model.id) model_name(asset.model.detail) } } } } return ['Content-Type': 'text/xml', 'Content': writer.toString()] Output: <Assets> <Asset> <id>98765</id> <name>testasset</name> <serial_number>testasset</serial_number> <model_id>4321</model_id> <model_name>testmodel</model_name> </Asset> </Assets Although XML is not a native Javascript object as is JSON, Javascript libraries and utilities are available for parsing XML into an object traversable in Javascript. For more information on parsing XML in Javascript, see W3 Schools XML Parser. For those using jQuery, check out the jQuery.parseXML function. Back to Top Outputting Files (Binary content types) CSV CSV comes in handy for spreadsheet generation as it is compatible with Microsoft Excel. The following example is suitable for Axeda version 6.1.6+ as it makes use of the Data Accumulator feature to create a downloadable file. import com.axeda.drm.sdk.device.ModelFinder import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.scripto.Request import com.axeda.common.sdk.id.Identifier import com.axeda.drm.sdk.device.Model import com.axeda.drm.sdk.device.DataItem import com.axeda.drm.sdk.device.DataItemValue import com.axeda.drm.sdk.data.DataValue import com.axeda.drm.sdk.device.DeviceFinder import com.axeda.drm.sdk.device.Device import com.axeda.drm.sdk.mobilelocation.MobileLocation import com.axeda.drm.sdk.data.DataValueList import com.axeda.drm.sdk.data.CurrentDataFinder import com.axeda.drm.sdk.mobilelocation.CurrentMobileLocationFinder import groovy.xml.MarkupBuilder import com.axeda.platform.sdk.v1.services.ServiceFactory /* * ExportObjectToCSV.groovy * * Creates a csv file from either all assets of a model of a single asset that can then be used to import them back into another system. * * @param model - (REQ):Str model name. * @param serial - (OPT):Str serial number. * * @author Sara Streeter <sstreeter@axeda.com> */ def writer = new StringWriter() def xml = new MarkupBuilder(writer) InputStream is try { Context CONTEXT = Context.getSDKContext() ModelFinder modelFinder = new ModelFinder(CONTEXT) modelFinder.setName(Request.parameters.model) Model model = modelFinder.find() DeviceFinder deviceFinder = new DeviceFinder(CONTEXT) deviceFinder.setModel(model) List<Device> devices = [] def exportkey = model.name Device founddevice if (Request.parameters.serial){ deviceFinder.setSerialNumber(Request.parameters.serial) founddevice = deviceFinder.find() logger.info(founddevice?.serialNumber) if (founddevice != null){ devices.add(founddevice) } else throw new Exception("Device ${Request.parameters.serial} cannot be found.") exportkey += "${founddevice.serialNumber}" } else { devices = deviceFinder.findAll() exportkey += "all" } // use a Data Accumulator to store the information def dataStoreIdentifier = "FILE-CSV-export_____" + exportkey def daSvc = new ServiceFactory().dataAccumulatorService if (daSvc.doesAccumulationExist(dataStoreIdentifier, devices[0].id.value)) { daSvc.deleteAccumulation(dataStoreIdentifier, devices[0].id.value) } List<DataItem> dataItemList = devices[0].model.dataItems def firstrow = [ "model", "serial", "devicename", "conditionname", "currentlat","currentlng" ] def tempfirstrow = dataItemList.inject([]){list, dataItem -> list << dataItem.name; list } firstrow += tempfirstrow firstrow = firstrow.join(',') firstrow += '\n' daSvc.writeChunk(dataStoreIdentifier, devices[0].id.value, firstrow); CurrentMobileLocationFinder currentMobileLocationFinder = new CurrentMobileLocationFinder(CONTEXT) devices.each{ device -> CurrentDataFinder currentDataFinder = new CurrentDataFinder(CONTEXT, device) currentMobileLocationFinder.deviceId = device.id.value MobileLocation mobileLocation = currentMobileLocationFinder.find() def lat = 0 def lng = 0 if (mobileLocation){ lat = mobileLocation?.lat lng = mobileLocation?.lng } def row = [ device.model.name, device.serialNumber, device.name, device.condition?.name, lat, lng ] def temprow = dataItemList.inject([]){ subList,dataItem -> DataValue value = currentDataFinder.find(dataItem.name) def val = "NULL" val = value?.asString() != "?" ? value?.asString() : val subList << val subList } row += temprow row = row.join(',') row += '\n' daSvc.writeChunk(dataStoreIdentifier, devices[0].id.value, row); } // stream the data accumulator to create the file is = daSvc.streamAccumulation(dataStoreIdentifier, devices[0].id.value) def disposition = 'attachment; filename=CSVFile' + exportkey + '.csv' return ['Content-Type': 'text/csv', 'Content-Disposition':disposition, 'Content': is.text] } catch (def ex) { xml.Response() { Fault { Code('Groovy Exception') Message(ex.getMessage()) StringWriter sw = new StringWriter(); PrintWriter pw = new PrintWriter(sw); ex.printStackTrace(pw); Detail(sw.toString()) } } logger.info(writer.toString()) return ['Content-Type': 'text/xml', 'Content': writer.toString()] } return ['Content-Type': 'text/xml', 'Content': writer.toString()] Back to Top Image Files (6.5+) The FileStore in Axeda version 6.5+ allows fine-grained control of uploaded and downloaded files. As Groovy scripts can return binary data via Scripto, this allows use cases such as embedding a Groovy script url as the source for an image. The following example uses the FileStore API to create an Image out of a valid image file, scales it to a smaller size and stores this smaller file. import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.data.* import com.axeda.drm.sdk.device.* import com.axeda.drm.sdk.mobilelocation.CurrentMobileLocationFinder import com.axeda.drm.sdk.mobilelocation.MobileLocation import com.axeda.drm.sdk.mobilelocation.MobileLocationFinder import com.axeda.sdk.v2.bridge.FileInfoBridge import static com.axeda.sdk.v2.dsl.Bridges.* import com.axeda.services.v2.ExecutionResult import com.axeda.services.v2.FileInfo import com.axeda.services.v2.FileInfoReference import com.axeda.services.v2.FileUploadSession import net.sf.json.JSONObject import groovy.json.JsonBuilder import net.sf.json.JSONArray import com.axeda.drm.sdk.scripto.Request import org.apache.commons.io.IOUtils import org.apache.commons.lang.exception.ExceptionUtils import com.axeda.common.sdk.id.Identifier import groovy.json.* import javax.imageio.ImageIO; import java.awt.RenderingHints import java.awt.image.BufferedImage import java.io.ByteArrayOutputStream; import java.awt.* import java.awt.geom.* import javax.imageio.* import java.awt.image.* import java.awt.Graphics2D import javax.imageio.stream.ImageInputStream /* Image-specific FileStore entry point to post and store files */ def contentType = "application/json" final def serviceName = "StoreScaledImage" // Create a JSON Builder def json = new JsonBuilder() // Global try/catch. Gotta have it, you never know when your code will be exceptional! try { Context CONTEXT = Context.getSDKContext() def filesList = [] def datestring = new Date().time InputStream inputStream = Request.inputStream def reqbody = Request.body // all of our Request Parameters are available here def params = Request.parameters def filename = Request?.headers?.'Content-Disposition' ? Request?.headers?.'Content-Disposition' : "file___" + datestring + ".txt" def filelabel = Request.parameters.filelabel ?: filename def description = Request.parameters.description ?: filename def contType = Request.headers?."content-type" ?: "image/jpeg" def tag = Request.parameters.tag ?: "cappimg" def encoded = Request.parameters.encoded?.toBoolean() def dimlimit = params.dimlimit ? params.dimlimit : 280 // host is available in the headers when the script is called with AJAX def domain = Request.headers?.host byte[] bytes = IOUtils.toByteArray(inputStream); def fileext = filename.substring(filename.indexOf(".") + 1,filename.size()) def outerMap = [:] // check that file extension matches an image type if (fileext ==~ /([^\s]+(\.(?i)(jpg|jpeg|png|gif|bmp))$)/){ if (inputStream.available() > 0) { def scaledImg try { def img = ImageIO.read(inputStream) def width = img?.width def height = img?.height def ratio = 1.0 def newBytes if (img){ if (width > dimlimit || height > dimlimit){ // shrink by the smaller side so it can still be over the limit def dimtochange = width > height ? height : width ratio = dimlimit / dimtochange width = Math.floor(width * ratio).toInteger() height = Math.floor(height * ratio).toInteger() } newBytes = doScale(img, width, height, ratio, fileext) if (newBytes?.size() > 0){ bytes = newBytes } } } catch(Exception e){ logger.info(e.localizedMessage) } outerMap.byteCount = bytes.size() FileInfoBridge fib = fileInfoBridge FileInfo myImageFile = new FileInfo(filelabel: filelabel, filename: filename, filesize: bytes?.size(), description: description, tags: tag ) myImageFile.contentType = contType FileUploadSession fus = new FileUploadSession(); fus.files = [myImageFile] ExecutionResult fer = fileUploadSessionBridge.create(fus); myImageFile.sessionId = fer.succeeded.getAt(0)?.id ExecutionResult fileInfoResult = fib.create(myImageFile) if (fileInfoResult.successful) { outerMap.fileInfoSave = "File Info Saved" outerMap.sessionId = "File Upload SessionID: "+fer.succeeded.getAt(0)?.id outerMap.fileInfoId = "FileInfo ID: "+fileInfoResult?.succeeded.getAt(0)?.id ExecutionResult er = fib.saveOrUpdate(fileInfoResult.succeeded.getAt(0).id,new ByteArrayInputStream(bytes)) def fileInfoId = fileInfoResult?.succeeded.getAt(0)?.id String url = "${domain}/services/v1/rest/Scripto/execute/DownloadFile?fileId=${fileInfoId}" if (er.successful) { outerMap.url = url } else { outerMap.save = "false" logger.info(logFailure(er,outerMap)) } } else { logger.info(logFailure(fileInfoResult, outerMap)) } } else { outerMap.bytesAvail = "No bytes found to upload" } } else { outerMap.imagetype = "Extension $fileext is not a supported image file type." } filesList << outerMap // return the JSONBuilder contents // we specify the content type, and any object as the return (even an outputstream!) return ["Content-Type": contentType,"Content":JSONArray.fromObject(filesList).toString(2)] // alternately you may just want to serial an Object as JSON: // return ["Content-Type": contentType,"Content":JSONArray.fromObject(invertedMessages).toString(2)] } catch (Exception e) { // I knew you were exceptional! // we'll capture the output of the stack trace and return it in JSON json.Exception( description: "Execution Failed!!! An Exception was caught...", stack: ExceptionUtils.getFullStackTrace(e) ) // return the output return ["Content-Type": contentType, "Content": json.toPrettyString()] } def doScale(image, width, height, ratio, fileext){ if (image){ ByteArrayOutputStream baos = new ByteArrayOutputStream(); def bytes def scaledImg = new BufferedImage( width, height, BufferedImage.TYPE_INT_RGB ) Graphics2D g = scaledImg.createGraphics(); g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR); g.scale(ratio,ratio) g.drawImage(image, null, null); g.dispose(); ImageIO.write( scaledImg, fileext, baos ) baos.flush() bytes = baos.toByteArray() baos.close() } else { logger.info("image to be scaled is null") return false } return bytes } private void logFailure(ExecutionResult fileInfoResult, LinkedHashMap outerMap) { outerMap.message = fileInfoResult.failures.getAt(0)?.message outerMap.source = fileInfoResult.failures.getAt(0)?.sourceOfFailure outerMap.details = fileInfoResult.failures.getAt(0)?.details?.toString() outerMap.fileInfoSave = "false" } The next example makes use of the jQuery framework to upload an image to this script via an http POST. Note: This snippet is available as a jsFiddle at http://jsfiddle.net/LrxWF/18/ With HTML5 button: <input type="file" id="fileinput" value="Upload" /> var PLATFORM_HOST = document.URL.split('/apps/')[0]; // this is how you would retrieve the host on an Axeda instance var SESSION_ID = null // usually retrieved from login function included below /*** * Depends on jQuery 1.7+ and HTML5, assumes an HTML5 element such as the following: * <input type="file" id="fileinput" value="Upload" /> * **/ $("#fileinput").off("click.filein").on("click.filein", function () { fileUpload() }) var fileUpload = function () { $("#fileinput").off('change.fileinput') $("#fileinput").on('change.fileinput', function (event) { if (this.files && this.files.length > 0) { handleFiles("http://" + PLATFORM_HOST, this.files) } }) } var handleFiles = function (host, files) { $.each(files, function (index, file) { var formData = new FormData(); var filename = file.name formData.append(filename, file) var url = host + '/services/v1/rest/Scripto/execute/StoreScaledImage?filelabel=' + filename + "&tag=myimg" url = setSessionId(url) jQuery.ajax(url, { beforeSend: function (xhr) { xhr.setRequestHeader('Content-Disposition', filename); }, cache: false, cache: false, processData: false, type: 'POST', contentType: false, data: formData, success: function (json) { refreshPage(json) console.log(json) } }); }) } var setSessionId = function (url) { // you would already have this from logging in return url + "&sessionid=" + SESSION_ID } var refreshPage = function (json) { // here you would refresh your page with the returned JSON return } /*** * The following functions are not used in this demonstration, however they are necessary for a complete app and are found in axeda.js http://gist.github.com/axeda/4340789 ***/ function login(username, password, success, failure) { var reqUrl = host + SERVICES_PATH + 'Auth/login'; localStorage.clear() return $.get(reqUrl, { 'principal.username': username, 'password': password }, function (xml) { var sessionId = $(xml).find("ns1\\:sessionId, sessionId").text() // var sessionId = $(xml).find("[nodeName='ns1:sessionId']").text(); - no longer works past jquery 1.7 if (sessionId) { // set the username and password vars for future logins. storeSession(sessionId); success(SESSION_ID); // return the freshly stored contents of SESSION_ID } else { failure($(xml).find("faultstring").text()); } }).error(function () { $('#loginerror').html('Login Failed, please try again') }); }; function storeSession(sessionId) { var date = new Date(); date.setTime(date.getTime() + SESSION_EXPIRATION); SESSION_ID = sessionId document.cookie = APP_NAME + '_sessionId=' + SESSION_ID + '; expires=' + date.toGMTString() + '; path=/'; return true; }; The return JSON includes a URL that you can use as the source for images: [{ "byteCount": 14863, "fileInfoSave": "File Info Saved", "sessionId": "File Upload SessionID: 01234", "fileInfoId": "FileInfo ID: 12345", "url": "http://yourdomain.axeda.com/services/v1/rest/Scripto/execute/DownloadFile?fileId=12345" }] The DownloadFile Custom Object looks like the following: import static com.axeda.sdk.v2.dsl.Bridges.* import javax.activation.MimetypesFileTypeMap import com.axeda.services.v2.* import com.axeda.sdk.v2.exception.* import com.axeda.drm.sdk.scripto.Request def knowntypes = [ [png: 'image/png'] ,[gif: 'image/gif'] ,[jpg: 'image/jpeg'] ] def params = Request.parameters.size() > 0 ? Request.parameters : parameters def response = fileInfoBridge.getFileData(params.fileId) def fileinfo = fileInfoBridge.findById(params.fileId) def type = fileinfo.filename.substring(fileinfo.filename.indexOf('.') + 1,fileinfo.filename.size()) type = returnType(knowntypes, type) def contentType = params.type ?: (type ?: 'image/jpg') return ['Content': response, 'Content-Disposition': contentType, 'Content-Type':contentType] def returnType(knowntypes, ext){ return knowntypes.find{ it.containsKey(ext) }?."$ext" } Make sure to append a valid session id to the end of the URL when using it as the source for an image. The techniques discussed above can be applied to any type of binary file output with consideration for the type of file being processed. A Word on Streaming Content streaming such as streaming of video or audio files over UDP is not currently supported by the Axeda Platform.

May 25, 2016

Data is NOT free. It is easy to overlook the cost of data collection, but all data incurs some cost when it is collected. Data collection in and of itself does not bring business value. If you don’t know why you’re collecting the data, then you probably won’t use it once you have it. For a wireless product, it is felt in the cost of bytes transferred, which makes for an expensive solution, but happy Telco's. Even for wired installations, data transfer isn’t free. Imagine a supermarket with 20 checkout lanes - with only a 56K DSL line - and the connection is shared with the credit card terminals, so it is important to upload only the necessary data during business hours. For the end user, too much data leads to information clutter. Too much information increases the time necessary to locate and access critical data. All enterprise applications have some associated "Infrastructure Tax", and the Axeda Platform is no exception. This is the cost of maintaining the existing infrastructure, as well as increasing capacity through the addition of new systems infrastructure. This includes: The cost of the physical hardware The additional software licenses The cost of the network bandwidth The cost of IT staff to maintain the servers The cost of attached storage Optimizing your data profile will maximize the performance of your existing infrastructure. Scaling decisions should be based on load because 50,000 well defined Assets can yield less data than 2,000 extremely "chatty" Assets. Types of Data To develop your data profile, first identify the types of data you’re collecting. "Actionable Data": This is used to drive business logic. This is your most crucial data, and tends to be "real-time" "Informational Data": This changes at a very low rate, and represents properties of your assets as opposed to status "Historical Data": Sometimes you need to step back to appreciate a work of art. Historical data is best viewed with a wide lens to identify trends "Payload Data": Data which is being packaged and shipped to an external system Actionable Data Actionable Data controls the flow of business logic and has three common attributes: It tends to represent the status of the Asset It typically the highest priority data you will receive It usually has more frequent occurrences than other data Informational Data Informational Data is typically system or software data of which some examples include: OS Version Firmware information Geographical region Historical Data Historical Data will represent the results of long-term operations and is typically used for operational review of trends. May be sourced either from Data Items, File uploads or Web Services operations May feed the Axeda integrated business intelligence solution, or internal customer BI systems Payload Data Payload data travels through the Cloud to your system of record. In this case, the Axeda Platform is a key actor in your system, but its presence is not directly visible to the end user Data Types Key Points Understanding the nature of your data helps to inform your data collection strategy. The four primary attributes are the following: Frequency Quantity Storage Format Knowing what to store, what to process and what to pass through for storage is the first key to optimizing your data profile. The "everything first" approach is an easy choice, but a tough one from which to realize value. A "bottom up" or use-case driven approach will add data incrementally, and will reveal the subset of data you actually need to be collecting.Knowing your target audience for the data is the next step. A best practice to better understand who is trying to innovate and how they are looking to do it begins with questions such as the following: Is marketing looking for trends to highlight? Is R&D looking for areas to improve the product? Is the Service team looking to pro-actively troubleshoot assets in the field? Is Sales looking to sell more consumables? Is Finance trying to resolve a billing dispute? Answers to these questions will help determine which data contributes to solving real business problems. Most Service technicians only access a handful of pieces of information about an Asset while troubleshooting, regardless of how many they have access to. It’s important to close the information loop when finding out which data is actually being used.In addition to understanding the correct target audience and their goals, milestone events are also opportunities to revisit your strategy, specifically times like: New Model rollouts Migration to the Cloud New program launch Once your data profile has been established, the next phase of optimization is to plan the way the data will be received. Strategies Data Item vs. File Upload A decision should be made as to the best way to transfer data to the Axeda Platform, whether that is data items, events, alarms or file transfers. Here's a Best Practice approach that's fairly universal: Choose a Data Item if: (a)You are sending Actionable Data, or (b)You are sending discreet Informational Data Choose a File Upload if: (a)You are sending bulk Data which does not need to trigger an immediate response, or (b)You intend to forward the Data to an external system Agent-Side Business Logic Keep in mind that the Axeda Platform allows business logic to be implemented before transmitting any data. The Agent can be configured to determine when Data needs to be sent via numerous mechanisms: Scripts provide the ability to trigger on-demand uploads of data, either via a human UI interaction or an automated process The "Black Box" configuration allows for a rolling sample window, and will only upload the data in the window based on a configured condition Agent Rules Agent Rules allow the Agent to monitor internal data values to decide when to send data to the Cloud. Data can be continuously sampled and compared against configured thresholds to determine when a value worthy of transmission is encountered. This provides a very powerful mechanism to filter outbound data. The example below shows a graphical representation of how an Agent might monitor a data flow and transmit only when it reaches an Absolute-high value of 1200: Axeda provides a versatile platform for managing the flow of data through your Asset ecosystem. It helps to cultivate an awareness not only of what the data set is but what it represents and to whom it has value. While data is cheap, the hidden costs of data transmission make it worthwhile to do your "data profiling homework" or risk paying a high price in the longer term.

May 24, 2016

The Axeda Platform has a mature data model that's important to understand when planning to build applications. First, this will introduce the existing objects and how they relate to each other. Axeda Agents can communicate Model – the definition of a type of asset. The model consists of a set of dataitems (its inputs and outputs) and alarms. The platform applies logic to a model, so as assets grow, the system is scalable in terms of management. Asset – or sometimes called Device. An asset has an identifier called a Serial Number which must be unique within its model. Agents report information in terms of the asset. Logic is applied to data and events about that asset. Dataitem – a named reading, such as a sensor or computer value. Dataitems are timestamped values in a sequence. For example, hourly temperatures, or odometer readings, or daily usage statistics. The number of named dataitems is unlimited. Dataitems can be written as well as read, so a value can be sent to an “output”. A dataitem can be a Digital (boolean), Analog (real value) or a String. Mobile Location - a lat/long pair typically read from GPS. This is used to map assets as they move. Alarms – have a name, severity, description, active flag, timestamp, and optional embedded dataitem and value. Alarms sent from an agent may result from logic that detects a condition, or from traps, error codes, etc. An alarm indicates something that's wrong. Files – arbitrary files can be uploaded from an agent. Files are sent with a Hint string. This is metadata that allows rules to process the file based on something other than the file extension. Files are often uploaded when an alarm has been raised, or on demand from a user or rule. Axeda agents have flexible ways to send and receive this information based on time, data changes, user request, etc. The Adaptive Machine Messaging Protocol (AMMP) allows anyone to make an agent that interacts with Axeda Platform using the same data model. Axeda Platform is asset-centric. An asset is an instance of a Model. Each asset is identified by its Model and Serial Number pair. Associated with an asset is Organization (typically the customer) Location or home of the asset (a street address). A location is in a Region. Contacts – people who have a relationship to the asset. Contacts have a role, such as Owner, or Service Agent. Asset Groups – assets are members of groups, and groups can be used to grant privileges, for navigation, or to apply commands. Properties – are additional named attributes of an asset. Properties do not have a time series history like a dataitem. The value of a property may be used to dynamically group assets. Condition – the current condition may be good, warning, error, or needs maintenance, based on the existence of alarms, for example. And, of course, dataitems, alarms and files. Information is processed and organized in the context of an asset, but the processing is managed for models. The only scalable way to manage a lot of assets is to apply rules by kind of asset, not individual assets. Rules apply logic to data as it happens. When a new dataitem is reported, a rule may check against its threshold. When an alarm is created, a rule may create a trouble ticket, or notify the user. All types of rules in the platform – Expression Rules, State Machines, and Threshold Rules – are event based. Rules apply to models, or sometimes to all (such as a standard way of notification on Alarms). The only exceptions are rules that apply to user logins and rules on a system timer. Software packages are another entity in the Platform. Packages are used to distribute files, software, patches, etc. and to script some commands around their delivery. So packages often upgrade or patch software, or load a new option of help file. Packages are defined for a model, and the deployment may be automatic or manual, to one or many.User logins are members of user groups. User groups have both privileges (what they can do) and visibility (which assets they can see). User group visibility allows the group to access assets in an Asset Group, or a Model or Region. How do solutions take advantage of this? Dataitems can be configured to store no data, current value, or history. History is needed if you want to see the temperature plot over the last day. Many times, current value is all that's needed to process rules and see the state of an asset. The option not to store a dataitem makes sense if the dataitem is only used to run a rule, or if it will just be sent to another application. An agent can send a dataitem string to the server, and the server puts the string on the Message Queue to deliver to another application. In a pass-through mode, the dataitem doesn't need to be stored at all. A similar situation is if a string dataitem is parsed by the rule calling a Groovy script. The script can parse the string (which may be XML or part of a log file) and use the SDK to do some action. Alarms are almost always used to notify people that they should do something. Alarms in Axeda have a lifecycle that corresponds to how people interact with them. An alarm begins its life when it's created. From that point, the alarm can be Acknowledged – this means that someone has seen it Escalated – the alarm condition hasn't been fixed for some time Closed – the end of the Alarm's life Suppressed – the alarm is logged in the history, but users don't see it. Set an alarm to suppressed when its just an annoyance and doesn't have any action required. Disabled – occurrences of this alarm are thrown away. Rules don't even see them. The Suppressed and Disabled modes are applied to an alarm of a given name, because they affect all future alarms by that name. Files are uploaded for a few reasons. Log files are typically uploaded so a service tech can diagnose a problem. Data files can be uploaded so a script or external system can process the file and take appropriate action. This can be another way of sending information that doesn't fit in a dataitem. The configuration of an asset – both hardware and software – is called Inventory, and the inventory of assets is important in diagnostics, planning spare parts, knowing what patch to apply, and many more. Extended Objects are attributes that can be added to the objects described here, or can be complete objects that live on their own. Your application can read and write these objects or attributes, and query them. The use is up to you. Resources You can find more information on the architecture of the platform in the Introduction to the Axeda Platform. The Platform SDK and Web Services expose most of these objects for configuration as well as runtime. That means an application can provision models and assets, create the rules and apply them to models, then monitor the behavior of assets, all through Web Services.

May 24, 2016

Adaptive Machine Messaging Protocol The Adaptive Machine Messaging Protocol (AMMP) is a simple, byte-efficient, lightweight messaging protocol used to facilitate Internet of Things (IoT) communications and to build IoT connectivity into your product. Using a RESTful API, AMMP provides a semantic structure for IoT information exchange and leverages HTTPS as the means for sending and receiving messages between an edge device and the Axeda® Machine Cloud®. AMMP uses JavaScript Object Notation (JSON) allowing any device that is capable of making an HTTP transmission to interact with the Axeda Platform. Utilizing a common network transport that is friendly to local network proxies and firewalls, and at the same time using JSON for a compact, human-readable, language-independent, and easily constructed data representation, AMMP simplifies device communication and reduces the work needed to connect to the Axeda Machine Cloud. For complete information about the Adaptive Machine Messaging Protocol, refer to the Adaptive Machine Messaging Protocol (AMMP) Technical Reference. AMMP Toolkits The AMMP Toolkits are libraries that allows you to connect your devices to the Axeda Platform using AMMP. The AMMP Toolkits support transmission of data, alarms, events, locations; error handling and reporting; as well as exchanging files with the Axeda Platform. AMMP Android-Based Toolkit The AMMP Android-Based Toolkit library conforms to the AMMP Protocol Version 1.1. AMMP Android Toolkit AMMP Android Toolkit Developers Reference AMMP Protocol v1.1 Technical Reference AMMP Java-Based ToolkitThe AMMP Java-Based Toolkit library conforms to the AMMP Protocol Version 1.1. AMMP Java Toolkit AMMP Java Toolkit Developers Reference AMMP Protocol v1.1 Technical Reference AMMP C-Based ToolkitThe AMMP C-Based Toolkit library conforms to the AMMP Protocol Version 1.1. AMMP C Toolkit AMMP C Toolkit Developers Reference AMMP Protocol v1.1 Technical Reference The above resources may be found at the PTC Support Portal.

May 24, 2016

While working with the Axeda Platform you will come across guard rails that limit sizes, recurrence, and duration of certain actions. When you run into these limitations, it may be an opportunity to re-examine the architecture of your solution and improve efficiency. What this tutorial covers This tutorial discusses the kinds of limits exist across the Platform, however it does not include the exact values of the limits as these may vary across instances. Skip to the last section on System Configuration to see how to determine the read-only properties of your Axeda Instance. You can also contact your Axeda Support technician to find out more about how these properties are configured. Types of Limits discussed: Rule Sniper Domain Object Field Length Constraints File Store Limits System Configuration Avoiding Rule Sniper Issues There are two ways a rule can be sniped from statistics (recursive rules are done differently) – frequency count and execution time. When a rule is killed, an email will be sent explaining the statistics behind the event. So what these numbers actually mean… CurrentAverageExecTime = loadExecTime / frequencyCount This determines which rule is sniped... This is the longest running rule on average, NOT the most running per time period. FrequencyCount = how many times this rule ran in this period This is for the rule in general - not this period TotalExecTime = total time this rule has executed for in a time MaxExecTime = longest time this rule has ever taken to run ExecCount = number of times this rule has ever run MaxFrequencyCount = max number of times this rule has ever run in a period The Rule Sniper monitors all the rules as a unit. When the entire system is beyond the “load point” it chooses the heaviest hitting rule and kills it. Some definitions: Execution count Execution count is how many time the rule has ran since it was last enabled. Maximum execution time Maximum execution time is the max time a rule can run. This is controlled by the setting of the following in your DRMConfig.properties: com.axeda.drm.rules.statistics.rule-time-threshold Total execution time Total execution is the time that the rule actually ran. Frequency count Frequency is how many times the same expression rule runs in a set period of time. The period of time is set in DRMConfig.properties by: com.axeda.drm.rules.statistics.rule-frequency-period Maximum frequency count Max frequency is the maximum times the expression can run Recursive expression Rules could be triggered from actions such as file uploads, device registration and data item changes. A scenario may occur in which an Expression Rule initiates a Then or Else action that triggers itself, such as a Data type Expression Rule setting a data item. This scenario has led to the existence of the Rule Sniper, which disables Expression Rules that are triggered several times in quick succession. At times an Expression Rule may be sniped simply for being triggered too many times in too short a period of time, even though the rule was not recursive. Setting a Data Item from a Data type Rule In one scenario, one data item comes in, say Temperature, and you need to set a different data item of Climate based on the value of Temperature. Without any checking, a Data type Rule that sets a Data Item Value will trigger itself, leading to a recursive rule execution that will be shut down by the Rule Sniper. A way to do this without the rule being sniped is to check in the If expression that the data item change triggering the rule is the one we are interested in, as opposed to the data item that is changed because it was set by the Rule. If: Temperature.changed && Temperature.value > 75 Then: SetDataItem("Climate", "Hot") Since it was the Climate that changed as a result of the Then statement, the rule will not be triggered again. ***Update: In an ironic twist of fate, it turns out that the solution above only works for data items that are set to be stored On Change rather than Stored data items. Stored data items are updated whenever a new value is entered, even if it is the same value. In this case, Temperature.changed would not trigger because the value would be the same, only the timestamp would be different. This would matter if you had the possibility of the same value happening twice consectively and needed the rule to trigger both times, but not on any other data item. The correct solution is the following: If: (!Temperature.changed || Temperature.changed) && Temperature.value > 75 Then: SetDataItem("Climate", "Hot") Admittedly inelegant, this works because if any other data item is passed in, Temperature will not be passed in so there will be no value for Temperature.changed. If Temperature is passed in, it will trigger either one of the cases (not changed if the value is the same, changed if it isn't). An alternate solution is to make use of the consecutive property of the Expression Rule. "Execute action each time rule evaluates to true" corresponds to the consecutive property, which determines whether the rule will fire every time the If expression evaluates to true. If the consecutive property is true, it will fire every time. If it is false, the rule will trigger one time when the If expression evaluates to true, and then it won't be triggered again until the If expression evaluates to false, and then to true again. With the consecutive property set to true, in our scenario above whenever the Temperature changes and is over 75, it will set Climate to Hot. With consecutive set to false, the rule will set Climate to Hot once, and then Temperature will have to fall below 75 and then rise above 75 again to trigger the rule again. Recurring Actions Sometimes you may need a recurring action to take place. An example would be if you don't need to evaluate a temperature in real time as it changes, but can check its status periodically. If the recurrence either requires or can tolerate a set delay, the best practice is to use a Rule Timer. A Rule Timer allows you to execute an Expression Rule on a schedule much like a cron job. In fact, the Rule Timer syntax is expressed in crontab format. In order to use a Rule Timer, create an Expression Rule of type System Timer or Asset Timer. The Asset Timer allows you to scope the rule to a certain set of assets like other rules, while a System Timer is not scoped to assets. This makes a System Timer more appropriate for a rule that would execute a Custom Object, as opposed to one that creates an alarm directly on an asset. Then create the Timer itself, which will allow you to set the schedule. Navigate to Configuration > New > Rule Timer With a Rule Timer, you can set a rule to run automatically with a preset delay and avoid the recurrence limit on the rule. For more information on the Rule Sniper, there is a Salesforce Knowledgebase Solution article available to Axeda customers called What are the Rule Sniper and Rule Executor Monitor Features For and How Do They Work? as well as the Rules Design and Best Practices Guide. Domain Object Field Length Constraints Every stored object has limits on the length of its fields, such as name and value. If a script attempts to store a value for a field that exceeds the field length constraints, the value will be truncated to the maximum limit. The maximum size of a data item value in the database is 4000 bytes. Two additional constraints are a limit on number of lines in a custom object (typically 1000 lines) and on the size of a stored data accumulation that can be read out as a string (1MB). The Help documentation available through the Axeda Applications Console contains information regarding field constraints (such as the Help pages on String Length Constraints at http://<<yourdomain>>.axeda.com/help/en/rule_action_data_entry_string.htm ). Limits on File Store Configurable quota limits exist on files that can be uploaded to the Axeda File Store via the SDK v2 FileInfoBridge. These limits will prevent creating FileUploadSessions, creating or updating FileInfos, or uploading file data if they are exceeded. File count: maximum number of files that can be stored on the system Maximum file size: the maximum size of any one file Total stored bytes: the total bytes for all files that may be stored on the system The configuration of these limits can be found on your system by navigating to Administration > System Configuration as described below and searching for "file" in the Read-Only Properties. System Configuration The System Configuration link under the Administration tab is a useful reference for viewing Read-Only properties of how your instance is configured. Check here when troubleshooting to determine any limit that may influence your app's implementation. Common Question An expression rule has a Data Trigger and in the Then Statement it sets a data item. Why is it getting disabled? Answer: The rule is being recursively triggered so the Rule Sniper is disabling it.

May 24, 2016

There's a reason why many "Hello World" tutorials begin with writing to the logging tool. Developers live in the console, inserting breakpoints and watching variables while debugging. Especially with interconnected, complex systems, logging becomes crucial to saving developer hours and shipping on time. What this tutorial covers This tutorial introduces the three principal methods of monitoring the status of assets and the output of operations on an Axeda instance. Audit Logs Custom Object Log Reports The Audit Log You can filter the Audit Log by date range or by category. A list of the Audit Categories is available in the Help documentation at http://<<yourhost>>.axeda.com/help/en/audit_log_categories_for_filtering... You can write to the Audit Log from an Expression Rule or from a Custom Object. Writing to the Audit Log from an Expression Rule Use the Audit Action to write to the Audit Log: Audit("data-management", "The temperature " + DataItem.temp.value + "was reported at " + FormatDate(Now(), "yyyy/MM/dd hh:mm:ss")) You can insert values from the Variables or Functions list by using the plus operator as a string concatenator. Writing to the Audit Log from a Custom Object import com.axeda.common.sdk.id.Identifier import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.audit.AuditCategory import com.axeda.drm.sdk.audit.AuditMessage auditMessage(Context.getSDKContext(), "data_management", "Thread started timestamp has ended.", context.device.id) private def auditMessage(Context CONTEXT, String category, String message, Identifier assetId) { AuditCategory auditCategory = AuditCategory.getByString(category) ?: AuditCategory.DATA_MANAGEMENT if (assetId == null) { new AuditMessage(CONTEXT, "com.axeda.drm.rules.functions.AuditLogAction", auditCategory, [message]).store() } else { new AuditMessage(CONTEXT, "com.axeda.drm.rules.functions.AuditLogAction", auditCategory, [message], assetId).store() } } In either case, a message written in the context of an Asset will be displayed on the Asset Dashboard (assuming the Audit module is enabled for the Asset Dashboard in the Model Preferences). The Custom Object Log The Configuration (6.1-6.5)/Manage(6.6+) tab provides access to the Custom Objects log when they are selected from the View sub-menu: This links allows you to open or save a zip archive of text files called customobject.logX where X is a digit that indicates that the log has rolled over into the next file (ie, customobject.log1). The most current is customobject.log without a digit. These files contain logging information in chronological order, identified by Custom Object name. The log contains full stack traces of exceptions, as well as text written to the log. ERROR 2013-06-20 18:26:02,613 [sstreBinaryReturn,ajp-10.16.70.164-8009-6] Exception occurred in sstreBinaryReturn.groovy: java.lang.NullPointerException at com.axeda.platform.sdk.v1.services.extobject.ExtendedObject.getPropertyByName(ExtendedObject.java:276) at com.axeda.platform.sdk.v1.services.extobject.ExtendedObject$getPropertyByName.call(Unknown Source) The Logger object in Custom Objects is a custom class ScriptoDebuggerLogger that is injected into the script and does not need to be explicitly imported. The following attributes are available for the Logger object: logger.info() logger.debug() logger.error() All objects can be converted to a String by using the dump() function. logger.info(context.device.dump()) Additionally, a Javascript utility can be used with all SDK v2 domain objects and some SDK v1 domain objects to get a JSON pretty-print string of their attributes. import net.sf.json.JSONArray logger.info(JSONArray.fromObject(context.device).toString(2)) // Outputs: [{ "buildVersion": "", "condition": { "detail": "", "id": "3", "label": "", "restUrl": "", "systemId": "3" }, "customer": { "detail": "", "id": "2", "label": "Default Organization", "restUrl": "", "systemId": "2" }, "dateRegistered": { "date": 31, "day": 4, "hours": 18, "minutes": 39, "month": 0, "seconds": 31, "time": 1359657571070, "timezoneOffset": 0, "year": 113 }, "description": "", "detail": "mwc_location_1", "details": null, "gateways": [], "id": "12345", "label": "", "location": { "detail": "Default Organization", "id": "2", "label": "Default Location", "restUrl": "", "systemId": "2" }, "model": { "detail": "mwc_location", "id": "4321", "label": "standalone", "restUrl": "", "systemId": "4321" }, "name": "mwc_location_1", "pingRate": 10000, "properties": [], "restUrl": "", "serialNumber": "mwc_location_1", "sharedKey": [], "systemId": "12345", "timeZone": "America/New_York" }] Custom object logs may be retrieved by navigating to the Configuration (6.1-6.5)/Manage(6.6+) tab and selecting Custom Objects from the View sub-menu. Click the "Log" button at the bottom of the table and save, then view customobject.log in a text editor. Reports Reports provide a summary of data about the state of objects on the Axeda Platform. Report titles are generally indicative of what they're reporting, such as Missing Devices Report, Auditing Report, Users Report. A separate license is needed in order to use the Reports feature. New report types can only be created by a Reports administrator. To run a report, click Run from the Reports Tab. You can manage Reports from the Administration tab. These three tools together offer a full view of the state of domain objects on the Axeda Platform. Make sure to take advantage of them while troubleshooting assets and applications.

May 24, 2016

Requirements: Axeda 6.1.6+ The Axeda Applications User Interface can be extended to accommodate varying degrees of customization. This ability to customize the base product enables repurposing the Axeda Applications User Interface to serve a specific audience. What this tutorial covers This tutorial discusses three ways to extend the Axeda Applications User Interface, which can be achieved via the following features: Customizing the Look and Feel - Use your own custom stylesheet to replace the default page styles, even on a per-user basis Extended UI Modules - Insert your own Extended UI Module into the Service > Asset Dashboard Custom Tab - Create a custom tab that loads content from a custom M2M application Customizing the Look and Feel of the Axeda Applications User Interface You can add style changes into a user.css file which you then upload like any other custom application, via the Administration > Extensions tab as a zip archive. Make sure to adhere to the expected directory structure and follow the naming convention for the zip archive. Images - store image files in a directory called <userName>/images Styles - store user.css and any style sheet(s) that it imports in a directory called <userName>/styles Documentation - store documentation files in a directory called <userName>/doc. The naming convention is to name the archive by the username of the user who should be able to see the changes, i.e. jsmith is the username so jsmith.zip is the archive name. For step-by-step instructions for customizing the UI, Axeda customers may refer to http://<<yourdomain>>.axeda.com/help/en/stylesheets_for_user_branding.htm andhttp://<<yourdomain>>.axeda.com/help/en/upload_user_branding.htm . Extended UI Modules Extended UI Modules can be added to the Asset Dashboard to provide custom content alongside the default modules. The modules can contain the output of a custom object or a custom application, all within the context of the particular asset being viewed. Create the Extended UI Content Option 1: an Extended UI Type Custom Object Navigate to Configuration > New > Custom Object This Custom Object should output HTML with any Javascript and/or CSS styling embedded inline. Parameters may be defined here and made available to the script as "parameters.label". Example: def iframehtml = """<html> <head> <script type='text/javascript' src='https://www.google.com/jsapi'></script> <script type='text/javascript'> google.load('visualization', '1', {packages:['gauge']}); google.setOnLoadCallback(drawChart); function drawChart() { var data = new google.visualization.DataTable(); data.addColumn('string', 'Label'); data.addColumn('number', 'Value'); data.addRows([ ['$parameters.label', $parameters.value] ]); var options = { redFrom: 90, redTo: 100, yellowFrom:75, yellowTo: 90, minorTicks: 5 }; var chart = new google.visualization.Gauge(document.getElementById('chart_div')); chart.draw(data, options); } </script> </head> <body style="background: white;"> <div id='chart_div'></div> </body> </html> """ return ['Content-Type': 'text/html', 'Content': iframehtml.toString()] Option 2: A Custom Application Create a zip file that contains an index html file at the root of the directory, any stylesheets, scripts and images you prefer and upload the zip as a Custom Application (see the example zip file included at the end of this article). Navigate to Administration > Extensions . Enter the information for the zip file and upload. Create the Extended UI Object Option 1: Using the Axeda Applications Console Navigate to Configuration > New > Extended UI Module Note that the parameters are entered in URI format myvalue=mykey&othervalue=otherkey If Content Source is set to Custom Application rather than Custom Object, the Custom Applications will become available as the Extended UI Module content. Option 2: Use Axeda Artisan Check out Developing with Axeda Artisan in order to make use of this method. Add the Extended UI Module to the apc-metadata.xml and it will be created for you automatically on Maven upload. Note that Artisan does not support Model Preferences, so you will still have to add the module through the Axeda UI as described below. <extendedUIModule>  <title>extendedUI_name</title> <height>180</height> <source> <type>CUSTOM_APPLICATION</type> <name>customapp_name</name> </source> </extendedUIModule> Add the Extended UI Module to the Model Preferences Navigate to Configuration > View > Model and click Preferences under UI Configuration next to the model that should display the Extended UI Module for its assets. Click Asset Dashboard Layout Select the Extended UI Module from the left and click the arrow to add it to the desired column. The asterisks indicate Extended UI Modules, as opposed to default modules. Click Submit and navigate to an Asset Dashboard to see the module displayed. Now you have an Extended UI Module with your custom content. Custom Tabs Upload a custom application as a custom tab. And there you have it. For Artisan developers, to enable a custom application as a custom tab, insert the following into the apc-metadata.xml: <application> <description>string</description> <applicationId>string</applicationId> <indexFile>string</indexFile> <zipFile>relative path from apc-metadata.xml to the zip file containing the application files</zipFile> <customTab> <tabPrivilegeName>the privilege name required for the tab to be shown</tabPrivilegeName> <afterTab>the name of the tab after which to place this tab</afterTab> <showFooter>[true|false]</showFooter> <tabNames> <label> <locale>the i18n locale (for example en_US or ja_JP)</locale> <name>the name to be displayed for the locale</name> </label> </tabNames> </customTab> </application> Authentication within Extended UI Components When working with Custom Applications in custom tabs or modules, the user session ID is made available through a special variable that you can access from the landing page (such as index.html) only: %%SESSIONID_TOKEN%% This variable is substituted directly for the session id, which makes the authentication for viewing the Extended UI component appear seamless to the end user. In order to make this ID available for AJAX calls, the index.html file should store the session ID as it is initializing. Additionally, index.html should instruct the browser not to cache the page, or the session ID may mistakenly be used to authenticate after it expires. In index.html: <html> <head> <title>My Custom App</title> <META HTTP-EQUIV="CACHE-CONTROL" CONTENT="NO-CACHE"> <link media="screen" href="styles/axeda.css" rel="stylesheet" type="text/css"/> <script src="scripts/jquery-1.9.0.min.js" type="text/javascript"></script> <script type="text/javascript"> $(window).load(function () { App.init(encodeURIComponent("%%SESSIONID_TOKEN%%")); }) </script> </head> In App.js: App.init = function (sessionID) { // put initial processing here storeSessionId( sessionID ) App.callScriptoWithStoredSessionID() } That's it! You can now customize the look and feel of the Axeda Applications Console, as well as add an Extended UI Module and a Custom Tab. Further Reading Developing with Axeda Artisan Axeda Sample Application: Populating A Web Page with Data Items Common Questions I want to display my custom app on a custom tab. How should I manage authentication within my custom tab app? Answer: Use Javascript to store the session ID injected as a variable into the index.html page, then use that to authenticate Scripto calls to the Axeda Platform. Are there example programs to get started? Answer: There are several examples of Artisan projects to get started Axeda Sample Application: Populating A Web Page with Data Items An Axeda instance - https://<customerInstance>.axeda.com/artisan

May 24, 2016

Scripto Editor is an enhanced Groovy Script Editor that allows the developer to compile and test uploaded Groovy Scripts on the fly. Please note that Scripto Editor is not a replacement for an IDE and should be used mainly for debugging Groovy Scripts. Installation: Download the Javascript Scripto Editor archive attached to this post. Install the archive as a custom app - Log into the Axeda Platform - Navigate to Administration > More Links -> Extended Applications - Click Browse and select the file downloaded in step 1. - Set the URL as "ScriptoEditor" - Set the Default Index as ScriptoEditor.html - Set Dsplay Mode as Standalone - Optionally enter a Description, such as Scripto Editor for Groovy Objects - Click Upload Open Scripto Editor by navigating to https://yourServicelink.axeda.com/apps/ScriptoEditor/ScriptoEditor.html Log in using your Axeda Platform credentials Double click any previously uploaded Groovy Script in the list to open Add or edit parameters in the Properties sidebar Test the script by clicking the Test tab in the sidebar and clicking "Run Test" Results will appear in the console at the bottom of the screen Save the Groovy Script by clicking "Save"Note: if the session expires before you have finished editing, the application will alert you with a pop up "Http Request Error". You will be unable to save your changes - at this point it is recommended to open a new tab and copy over your changes back into Scripto Editor. For this reason, Scripto Editor is not a replacement for an IDE and should be used sparingly for on-the-fly debugging.Additionally, any changes made in Scripto Editor will need to be manually copied back into the local development source code. WARNING: Scripto Editor has a 1000 line code limit. If your custom objects are longer than this, Scripto Editor will truncate them when saving!!

May 18, 2016

Introduction The Edge MicroServer (EMS) and Lua Script Resource (LSR) are Edge software that can be used to connect remote devices to the ThingWorx platform. Using a Gateway is beneficial because, this will allow you to run one instance of the EMS on a server and then many instances of the LSR on different devices all over the world. All communication to the platform will be handled by this one EMS Gateway server. The EMS Gateway can be set up in two different types of scenarios: Self-Identifying Remote Things and Explicitly defined Remote Things. The scenario I'm going to discuss below will involve explicitly defined Remote Things, a ThingWorx server, an EMS, and a LSR. We will need at least 1 server to run the ThingWorx platform and EMS, but these can always be on separate servers as well. We will also need some other machine or device that will run the LSR. Visit the support downloads page to find the latest EMS releases. The LSR is contained within the EMS download. You can also navigate to the Edge Support site to read more about the EMS and LSR oif this is the first time you have ever configured one. The "ThingWorx WebSocket-based Edge MicroServer Developer's Guide" is also provided inside of the zip file that contains the EMS for further information. Setting up the EMS Once we have obtained the EMS download from the support site (see the section above for links) we can begin creating our config.json file. The image below is a working config.json file for using the EMS as a Gateway. The settings in here are particular to my personal IP addresses and Application Key, but the concept remains the same, and I will go into further detail on the necessary sections, below the image. ws_servers The host and port parameters are always set to the IP address and port that the ThingWorx platform is being hosted on When the EMS and ThingWorx platform are on the same server, "localhost" can be used instead of an IP address appKey The appKey section is the value of an Application Key in the ThingWorx platform that should be used for the authentication of the EMS to the platform An Application Key will need to be created and assigned a user with proper priveledges prior to authenticating certificates The certificates section should be validating and pointing to proper certificates, but in the example above I am not validating any certificates for the sake of simplicity More can be read about the certificates sections here logger The logging section is out of scope of this article, but further reading on logger configurations can be found here The section in the example above will work for basic logging needs http_server The http_server section configuration parameters will tell the EMS what host and port to spin up a server on and if there is authentication necessary by any LSRs trying to connect The LSR has settings that will explicitly call out whatever value is set to the host and port in this section, so make sure to set these to an open port that is not in use or blocked behind a firewall Further reading on the http_server section can be found here auto_bind You can see above that there are two objects defined in the auto_bind section. One of these is binding the EMS to an EMSGateway Thing in the platform called "EdgeGateway" and the other is defined in the config.lua file for the LSR The gateway parameter is set to true only in the object, "EdgeGateway", that is being used for the EMS to bind to The host and port defined for the "OtherEdgeThing" should point to the port and IP address that the LSR is running on in the other device By default, the LSR runs on port 8001, but you can always double check the listening port by finding the Process Identification (PID) number of the luaScriptResource.exe and then matching the PID to the corresponding line item in the output of netstat -ao command in a console window The protocol can be set to "http" in an example application, but make sure to use "https" when security is of concern All further reading on the sections of the config.json file can be found in the config.json.complete file included with the EMS download and on the Edge Help Center under the "Creating a Configuration File" section and the "Viewing All Options" section. Setting up the LSR In this example, the LSR is going to run on a separate server and point to the EMS server. Below is a screenshot of two very important additions (rap_host and rap_port) to the default config.lua file: rap_host The rap_host field should be set to the IP address where the EMS is hosted rap_port The rap_port field should be set to the port parameter defined in the config.json http_server section script_resource_host The script_resource_host field must be set to ensure that the EMS will know what IP address to communicate with the LSR at scripts.OtherEdgeThing This line is necessary to identify what the name of the LSR is that will register with the EMS to bind to the platform "OtherEdgeThing" can be changed to anything, but make sure that the auto_bind section in the config.json aligns with what you've defined in the config.lua file at this line Running the EMS and LSR Now that we have configured the LSR and EMS to point to each other and the platform we can try running both of these applications to make sure we are successful. Make sure the ThingWorx platform is running Create a RemoteThing with the name given in the auto_bind section for the LSR we are connecting Create an EMSGateway with the name given in the auto_bind section for the EMS as a Gateway to bind to Start the EMS This can be done by double clicking the wsems.exe when in Windows, running it as a service, or running it directly from the command line Start the LSR This can be done by double clicking the luaScriptResource.exe when in Windows, running it as a service, or running it directly from the command line Navigate to the ThingWorx platform and make sure that the Things you have created are connected Do this by navigating to the Properties menu option and refreshing the isConnected property You should be able to browse remote properties and services for each bound RemoteThing, and this means you have successfully setup the EMS as a Gateway device to external LSR applications running on remote devices Any further questions about browsing remote properties or other configuration settings in the .config files is most likely addressed in the Edge Help Center under the EMS section, and if not, feel free to comment directly on this document.

May 16, 2016

This code snippet finds an uploaded file associated with an asset and emails it to a destination email address. It uses a data accumulator to create a temporary file. import org.apache.commons.codec.binary.Base64; import java.util.Date; import java.util.Properties; import java.io.StringWriter import java.io.PrintWriter import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.data.* import com.axeda.drm.sdk.device.* import groovy.json.JsonSlurper import javax.activation.DataHandler; import javax.activation.FileDataSource; import org.apache.axiom.attachments.ByteArrayDataSource; import com.axeda.platform.sdk.v1.services.ServiceFactory; import com.thoughtworks.xstream.XStream; import javax.mail.Authenticator; import javax.mail.Message; import javax.mail.MessagingException; import javax.mail.Multipart; import javax.mail.PasswordAuthentication; import javax.mail.Session; import javax.mail.Transport; import javax.mail.internet.AddressException; import javax.mail.internet.InternetAddress; import javax.mail.internet.MimeBodyPart; import javax.mail.internet.MimeMessage; import javax.mail.internet.MimeMultipart; try { Context ctx = Context.create(parameters.username) DeviceFinder dfinder = new DeviceFinder(ctx) def bytes dfinder.setSerialNumber(parameters.serial_number) Device d = dfinder.find() UploadedFileFinder uff = new UploadedFileFinder(ctx) uff.device = d def ufiles = uff.findAll() UploadedFile ufile if (ufiles.size() > 0) { ufile = ufiles[0] File f = ufile.extractFile() def slurper = new JsonSlurper() def objects = slurper.parseText(f.getText()) def bugreport = objects.objects[0].mobj_update[0].bugreport String from = "demo@axeda.com"; String to = "destination@axeda.com"; String subject = "My file"; String mailContent = "Attaching test"; String filename = "payload.tar.gz"; def dataStoreIdentifier = "FILE-IO-SUB-testing" def daSvc = new ServiceFactory().dataAccumulatorService if (daSvc.doesAccumulationExist(dataStoreIdentifier, d.id.value)) { daSvc.deleteAccumulation(dataStoreIdentifier, d.id.value) } daSvc.writeChunk(dataStoreIdentifier, d.id.value, bugreport); InputStream is = daSvc.streamAccumulation(dataStoreIdentifier, d.id.value) Base64 base64 = new Base64() ByteArrayDataSource rawData = new ByteArrayDataSource(base64.decodeBase64(is.getBytes())); // You need to create a properties object to store mail server // smtp information such as the host name and the port number. // With this properties we create a Session object from // which we'll create the Message object. Properties properties = new Properties(); properties.put("mail.smtp.host","mail01.bo2.axeda.com"); properties.put("mail.smtp.port", "25"); properties.put("mail.smtp.auth", "true"); Authenticator authenticator = new CustomAuthenticator(); Session session = Session.getInstance(properties, authenticator); MimeMessage message = new MimeMessage(session); message.setFrom(new InternetAddress(from)); message.setRecipient(Message.RecipientType.TO, new InternetAddress(to)); message.setSubject(subject); message.setSentDate(new Date()); // Set the email message text. MimeBodyPart messagePart = new MimeBodyPart(); messagePart.setText(mailContent); // Set the email attachment file MimeBodyPart attachmentPart = new MimeBodyPart(); // FileDataSource fileDataSource = new FileDataSource(file) attachmentPart.setDataHandler(new DataHandler(rawData)) //fileDataSource)); attachmentPart.setFileName(filename); Multipart multipart = new MimeMultipart(); multipart.addBodyPart(messagePart); multipart.addBodyPart(attachmentPart); // Set the content message.setContent(multipart); // Send the message with attachment Transport.send(message); } } catch (Exception e) { logger.info(e.message) StringWriter logStringWriter = new StringWriter(); PrintWriter logPrintWriter = new PrintWriter(logStringWriter) e.printStackTrace(logPrintWriter) logger.info(logStringWriter.toString()) } // This class is the implementation of the Authenticator // Where you need to implement the getPasswordAuthentication // to provide the username and password public class CustomAuthenticator extends Authenticator { protected PasswordAuthentication getPasswordAuthentication() { String username = ""; String password = ""; return new PasswordAuthentication(username, password); } } static byte[] getBytes(File file) throws IOException { return getBytes(new FileInputStream(file)); } static byte[] getBytes(InputStream is) throws IOException { ByteArrayOutputStream answer = new ByteArrayOutputStream(); // reading the content of the file within a byte buffer byte[] byteBuffer = new byte[8192]; int nbByteRead /* = 0*/; try { while ((nbByteRead = is.read(byteBuffer)) != -1) { // appends buffer answer.write(byteBuffer, 0, nbByteRead); } } finally { is.close() } return answer.toByteArray(); }

May 16, 2016

This code snippet creates then deletes a data item to illustrate CRUD technique. Parameter: model_number import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.device.ModelFinder import com.axeda.drm.sdk.device.Model import com.axeda.drm.sdk.device.DeviceFinder import com.axeda.drm.sdk.data.CurrentDataFinder import com.axeda.drm.sdk.device.Device import com.axeda.drm.sdk.data.HistoricalDataFinder import groovy.xml.MarkupBuilder import com.axeda.drm.sdk.device.DataItem import com.axeda.drm.services.device.DataItemType /* * DeleteDataItem.groovy * * Delete a data item. * * @param model_number - (REQ):Str name of the model. * * @author Sara Streeter <sstreeter@axeda.com> */ def response = [:] def writer = new StringWriter() def xml = new MarkupBuilder(writer) try { // getUserContext is supported as of release 6.1.5 and higher final def CONTEXT = Context.getUserContext() // find the model def modelFinder = new ModelFinder(CONTEXT) modelFinder.setName(parameters.model_name) Model model = modelFinder.findOne() // throw exception if no model found if (!model) { throw new Exception("No model found for ${parameters.model_name}.") } // Add a dummy data item DataItem dataitem = new DataItem(CONTEXT, model, DataItemType.STRING, "MyDataItem"); dataitem.store(); // find the data items on the model model.dataItems.each{ logger.info(it.name) if (it.name=="MyDataItem"){ it.delete() } } } catch (def ex) { xml.Response() { Fault { Code('Groovy Exception') Message(ex.getMessage()) StringWriter sw = new StringWriter(); PrintWriter pw = new PrintWriter(sw); ex.printStackTrace(pw); Detail(sw.toString()) } } } return ['Content-Type': 'text/xml', 'Content': writer.toString()]

May 16, 2016

This document is designed to help troubleshoot some commonly seen issues while installing or upgrading the ThingWorx application, prior or instead of contacting Tech Support. This is not a defined template for a guaranteed solution, but rather a reference guide that provides an opportunity to eliminate some of the possible root causes. While following the installation guide and matching the system requirements is sufficient to get a successfully running instance of ThingWorx, some issues could still occur upon launching the app for the first time. Generally, those issues arise from minor environmental details and can be easily fixed by aligning with the proper installation process. Currently, the majority of the installation hiccups are coming from the postgresql side. That being said, the very first thing to note, whether it's a new user trying out the platform or a returning one switching the database to postgresql, note that: Postgresql database must be installed, configured, and running prior to the further Thingworx installation. ThingWorx 7.0+: Installation errors out with 'failed to succeed more than the maximum number of allowed acquisition attempts' Platform being shut down because System Ownership cannot be acquired error ERROR: relation "system_version" does not exist Resolution: Generally, this type of error point at the security/permission issue. As all of the installation operations should be performed by a root/Administrator role, the following points should be verified: Ensure both Tomcat and ThingworxPlatform folders have relevant read/write permissions The title and contents of the configuration file in the ThingworxPlatform folder has changed from 6.x to 7.x Check if the right configuration file is in the folder Verify if the name and password provided in this configuration file matches the ones set in the Postgres DB Run the Database cleanup script, and then set up the database again. Verufy by checking the thingworx table space (about 53 tables should be created) Thingworx Application: Blank screen, no errors in the logs, "waiting for <url> " gears running be never actually loading, eventually times out Resolution: Ensure that Java in tomcat is pointing to the right path, should be something like this: C:\Program Files\Java\jre1.8.0_101\bin\server\jvm.dll 6.5+ Postgres: Error when executing thingworxpostgresDBSetup.bat psql:./thingworx-database-setup.sql:1: ERROR: could not set permissions on directory "D:/ThingworxPostgresqlStorage": Permission denied Resolution: The error means that the postgres user was not able to create a directory in the ‘ThingworxPostgresStorage’ directory. As it's related to the security/permission, the following steps can be taken to clear out the error: Assigning read/write permissions to everyone user group to fix the script execution and then execute the batch file: Right-click on ‘ThingworxPostgresStorage’ directory -> Share with -> specific people. Select drop-down, add everyone group and update the permission level to Read/Write. Click Share. Executing the batch file as admin. 2. Installation error message "relation root_entity_collection does not exist" is displayed with Postgresql version of the ThingWorx platform. Resolution: Such an error message is displayed only if the schema parameter passed to thingworxPostgresSchemaSetup.sh script is different than $USER or PUBLIC. To clear out the error: Edit the Postgresql configuration file, postgresql.conf, to add to the SEARCH_PATH item your own schema. Other common errors upon launching the application. Two of the most commonly seen errors are 404 and 401. While there can be a numerous reasons to see those errors, here are the root causes that fall under the "very likely" category: 404 Application not found during a new install: Ensure Thingworx.war was deployed -- check the hard drive directory of Tomcat/webapps and ensure Thingworx.war and Thingworx folder are present as well as the ThingworxStorage in the root (or custom selected location) Ensure the Thingworx.war is not corrupted (may re-download from the support and compare the size) 401 Application cannot be accessed during a new install or upgrade: For Postgresql, ensure the database is running and is connected to, also see the Basic Troubleshooting points below. Verify the tomcat, java, and database (in case of postgresql) versions are matching the system requirement guide for the appropriate platform version Ensure the updrade was performed according to the guide and the necessary folders were removed (after copying as a preventative measure). Ensure the correct port is specified in platform-settings.json (for Postgresql), by default the connection string is jdbc:postgresql://localhost:5432/thingworx Again, it should be kept in mind that while the symptoms are common and can generally be resolved with the same solution, every system environment is unique and may require an individual approach in a guaranteed resolution. Basic troubleshooting points for: Validating PostgreSQL installation Postgres install troubleshooting java.lang.NullPointerException error during PostgreSQL installation ***CRITICAL ERROR: permission denied for relation root_entity_collection Error while running scripts: Could not set permissions on directory "/ThingworxPostgresqlStorage":Permission Denied Acquisition Attempt Failed error Resolution: Ensure 'ThingworxStorage', 'ThingworxPlatform' and 'ThingworxPostgresqlStorage' folders are created The folders have to be present in the root directory unless specifically changed in any configurations Recommended to grant sufficient privileges (if not all) to the database user (twadmin) Note: While running the script in order to create a database, if a schema name other than 'public' is used, the "search_path" in "postgresql.conf" must be changed to reflect 'NewSchemaName, public' Grant permission to user for access to root folders containing 'ThingworxPostgresqlStorage' and 'ThingworxPlatform' The password set for the default 'twadmin' in the pgAdmin III tool must match the password set in the configuration file under the ThingworxPlatform folder Ensure THINGWORX_PLATFORM_SETTINGS variable is set up Error: psql:./thingworx-database-setup.sql:14: ERROR: could not create directory "pg_tblspc/16419/PG_9.4_201409291/16420": No such file or directory psql:./thingworx-database-setup.sql:16: ERROR: database "thingworx" does not exist Resolution: Replacing /ThingworxPostgresqlStorage in the .bat file by C:\ThingworxPostgresqlStorage and omitting the -l option in the command window. Also, note the following error Troubleshooting Syntax Error when running postgresql set up scripts

May 13, 2016

The past few years has seen a tremendous explosion in the numbers of devices with Internet connectivity, and the Axeda product has continued to evolve to meet the requirements of these devices, which are often memory and CPU constrained. Beginning with the Axeda Platform 6.6 release, the Axeda Adaptive Machine Messaging Protocol (AMMP) has been available that allows any device that can make an HTTP GET/POST request to send data to the Axeda Machine Cloud. AMMP uses standard, JSON messages sent inside HTTP requests. How to get AMMP AMMP is a separately available product that can be added to an Axeda installation. Customers should discuss with their Account Managers to get access to the Axeda AMMP product offering. AMMP is a device codec that requires the installation of the Axeda AnyDevice Codec Server (ACS) component. This configuration presents a new endpoint for customer installations - an https://example.axeda.com instance will have an ACS instance available at https://example-connect.axeda.com. Self-hosted customers can create their own hosting/URL infrastructure, but this is the default available to Axeda On-Demand Center customers. How to set up assets to talk AMMP Before you can start deploying devices to talk AMMP to an Axeda instance, a Model Communication Profile must be created for any Model that is expected to communicate with the AMMP protocol. This is required in order to configure the proper egress mechanism so that the device can get access to messages waiting for it on the Axeda Platform. Attached to this document is a file called AMMP_CreateCommProfile.groovy.zip. This file contains a Groovy-based script that is copied into the Platform as a Custom Object, and then executed via Scripto - this is needed to be run for each device Model that requires access via AMMP. First Requests Since all requests are via HTTP, it is useful to acquire a client that can perform REST API requests. One highly recommended client is Postman (available in Chrome and standalone versions). The first time a device connects to the Axeda Machine Cloud it should send a registration message. A registration message must contain a model and serial number and can optionally include a ping rate. The ping rate is how often the server should expect to hear from the device. The server will mark a device as off-line if it does not get a message before a configurable number ping times pass. A device should also send a registration message whenever it powers up. Using Postman, select POST from the drop down next to the URL. Enter the URL as shown below to register a new device. https://example-connect.axeda.com/ammp/assets/1 (Customers should use their own instances in the following examples) Click Headers to add a header named 'Content-Type' with value of 'application/json': Click the Body button and enter the line below. The "mn" field below should be an already registered and configured model. { "id": { "mn" : "ExampleModel", "sn" : "ExampleDevice-001", "tn" : 0 }, "pingRate": 60 } Click the Send button - an HTTP 200 OK response should be the expected result. Logging into the platform and searching for 'ExampleDevice-001' should show that it is registered Now that a device has been registered is is now possible to send live information to the Axeda Machine Cloud. Sending information is also done with a POST to a URL. Instead of the asset's resource, we will be sending to the data resource. Using Postman, the HTTP POST request will be structured like follows: http://example-connect.axeda.com/ammp/data/1/ExampleModel!ExampleDevice-001 Change the body as follows: {"alarms":[{"name":"over_temp","description":"freezer hot" }]} Click on the 'Send' button and after the response returns, the alarm can be seen in the Asset Status Page in the Axeda Machine Cloud. Four different types of information can be sent to the data resource and any or all can be included in one POST message. All four types can have an optional time and priority field. If no time is specified, the time on the server at arrival will be added. Alarm Field Name Purpose Expected Data Type Required? Format, Range Default Value Default Behavior name Identify the alarm String Yes Length: 0 <= N <= ? Valid String Characters description Describe the alarm String No Length: 0 <= N <= ? None severity Describe the severity Integer No Range: 0 <= N <= 1000 0 cause Identify the cause String No Length: 0 <= N <= ? None reason Describe the cause String No Length: 0 <= N <= ? None time Time when the alarm occurred No ISO-8601 or Unix Epoch None Use server time if <Default Value> priority How much priority the server should give to processing No 1 <= N <= 100 1 Alarm Example JSON { "alarms": [ { "name": "RadiationLeak", "description": "A radiation leak has been detected", "severity": 1000, "cause": "CoolantPipeBurst", "reason": "The main coolant pipe exploded", "time": 1364443200000, "priority": 100 } ] } Once alarms reach the Axeda Machine Cloud, they will be in the "Started" state. Once an alarm is received, it can be "Acknowledged", "Escalated", or "Closed". Event Field Name Purpose Expected Data Type Required? Format, Range Default Value Default Behavior name Identify the event String Yes Length: 0 <= N <=? Valid String Characters description Describe the event String No Length: 0 <= N <= ? None time Time when the event occurred Integer (Epoch Timestamp) String (ISO-8601) No ISO-8601 or Unix Epoch None Use server time if <Default Value> priority How much priority the server should give to processing Integer No 1 <= N <= 100 1 Event Example JSON { "events": [ { "name": "RadiationLeak", "description": "A radiation leak has been detected", "time": 1364443200000, "priority": 100 } ] } Mobile Location Field Name Purpose Expected Data Type Required? Format, Range Default Value Default Behavior latitude Latitude Float Yes -90 <= N <= +90 longitude Longitude Float Yes -180 <= N <= +180 altitude Altitude/Elevation Float No Unbounded time Time when the event occurred Integer (Epoch Timestamp) String (ISO-8601 Timestamp) No ISO-8601 or Unix Epoch None Use server time if <Default Value> priority How much priority the server should give to processing Integer No 1 <= N <= 100 1 Location Example JSON { "locations": [ { "latitude": 42.034061, "longitude": -71.237472, "altitude": 0.0, "time": 1364443200000, "priority": 100 } ] } Note: The platform records the history of all the mobile locations a device has reported. This has implications for the positions displayed in the Asset Status Map Charting components. Data Item Set Field Name Purpose Expected Data Type Required? Format, Range Default Value Default Behavior dataItems A collection of key/value pairs Object<String, JSON Type> Yes Unbounded time Time when the data items were sampled Integer (Epoch Timestamp) String (ISO-8601 Timestamp) No ISO-8601 or Unix Epoch None Use server time if <Default Value> priority How much priority the server should give to processing Integer No 1 <= N <= 100 1 Data Item Set Example JSON { "data" :[ { "dataItems": { "CurrentSong": "Comfortably Numb", "PreviousSong": "Rain When I Die", "NextSong": "Whole Lotta Love", "FreeMemory": 1237.24, "DebugModeEnabled": true }, "time": 1364443200000, "priority": 100 }, { "dataItems":{ "bar":"camp", "pot1":23.3 }, "time": 1364443234000, "priority": 100 } ]} Data Items are sent as sets that share a common recording time and priority. Data Item values follow JSON representation standards and can be: string, numeric, or Boolean. Below is an example message showing all four information types that can be sent: { "alarms": [ { "name": "RadiationLeak", "description": "A radiation leak has been detected", "time": 1364443200000 } ], "events": [ { "name": "Foo", "description": "A Foo occurred" } ], "data":[ { "dataItems":{ "bar":"camp", "pot1":23.3}, "time": 1364443200000 } ], "locations": [ { "latitude": 32.00, "longitude": -78.00 } ] } Polling Axeda AMMP is designed to provide a minimalist communication protocol between devices. As such each request has egress items returned in the HTTP response body, no matter the type of data sent as the request body. This is so that extra requests to retrieve egress do not have to be made. But if a device has no updates to make, it is still able to make periodic polling requests to the Codec Server to get any egress items available to it. This request is simply a REST request of HTTP POST to the example URL: https://example-connect.axeda.com/ammp/assets/1/ExampleModel!ExampleDevice-001 with an empty request body. Next steps and caveats Keep in mind that egress data can be returned in ANY HTTP response body. If a device has a programming error or a power failure occurs before the request is processed, then it is possible that request can be lost - permanently. The Axeda Platform does not replay egress items once it has been delivered to the device. Additional logical facilities are available on the Axeda Platform to be able to provide replay/retry communications to the device. Bibliography Using Axeda Scripto Axeda AMMP Technical Reference (1.2.0 Dec 2014)

May 12, 2016

The following script takes a parameter of a model name, a device serial number and a data item name, finds the asset location and uses that longitude to determine the current TimeZone. It then converts the Timezone of the data item timestamp to an Eastern Standard Timezone timestamp. import groovy.xml.MarkupBuilder import com.axeda.drm.sdk.Context import java.util.TimeZone import com.axeda.drm.sdk.data.* import com.axeda.drm.sdk.device.* import com.axeda.common.sdk.jdbc.*; import net.sf.json.JSONObject import net.sf.json.JSONArray import com.axeda.drm.sdk.mobilelocation.MobileLocationFinder import com.axeda.drm.sdk.mobilelocation.MobileLocation import com.axeda.drm.sdk.mobilelocation.CurrentMobileLocationFinder def response try { Context ctx = Context.getUserContext() ModelFinder mfinder = new ModelFinder(ctx) mfinder.setName(parameters.model_name) Model m = mfinder.find() DeviceFinder dfinder = new DeviceFinder(ctx) dfinder.setModel(m); dfinder.setSerialNumber(parameters.device) Device d = dfinder.find() CurrentMobileLocationFinder cmlFinder = new CurrentMobileLocationFinder(ctx); cmlFinder.setDeviceId(d.id.getValue()); MobileLocation ml = cmlFinder.find(); def lng = -72.158203125 if (ml?.lng){ lng = ml?.lng } // set boundaries for timezones - longitudes def est = setUSTimeZone(-157.95415000000003) def tz = setUSTimeZone(lng) CurrentDataFinder cdfinder = new CurrentDataFinder(ctx, d) DataValue dvalue = cdfinder.find(parameters.data_item_name) def adjtime = convertToNewTimeZone(dvalue.getTimestamp(),tz,est) def results = JSONObject.fromObject(lat: ml?.lat, lng: ml?.lng, current: [name: dvalue.dataItem.name, time: adjtime.format("MM/dd/yyyy HH:mm"), value: dvalue.asString()]).toString(2) response = results } catch (Exception e) { response = [ message: "Error: " + e.message ] response = JSONObject.fromObject(response).toString(2) } return ['Content-Type': 'application/json', 'Cache-Control':'no-cache', 'Content': response] def setUSTimeZone(lng){ TimeZone tz // set boundaries for US timezones by longitude if (lng <= -67.1484375 && lng > -85.517578125){ tz = TimeZone.getTimeZone("EST"); } else if (lng <= -85.517578125 && lng > -96.591796875){ tz = TimeZone.getTimeZone("CST"); } else if (lng <= -96.591796875 && lng > -113.90625){ tz = TimeZone.getTimeZone("MST"); } else if (lng <= -113.90625){ tz = TimeZone.getTimeZone("PST"); } logger.info(tz) return tz } public Date convertToNewTimeZone(Date date, TimeZone oldTimeZone, TimeZone newTimeZone){ long oldDateinMilliSeconds=date.time - oldTimeZone.rawOffset // oldtimeZone.rawOffset returns the difference(in milliSeconds) of time in that timezone with the time in GMT // date.time returns the milliseconds of the date Date dateInGMT=new Date(oldDateinMilliSeconds) long convertedDateInMilliSeconds = dateInGMT.time + newTimeZone.rawOffset Date convertedDate = new Date(convertedDateInMilliSeconds) return convertedDate }

May 12, 2016

The following script is a component of the Axeda Connected Configuration (CMDB) feature. It is used to provide configuration data for controlling package deployments via Connected Content (SCM). ConfigItem_CRU.groovy *Takes a POST request, not parameters import static com.axeda.sdk.v2.dsl.Bridges.* import com.axeda.drm.sdk.scripto.Request import com.axeda.services.v2.ConfigurationItem import com.axeda.services.v2.ConfigurationItemCriteria import com.axeda.services.v2.AssetConfiguration import com.axeda.services.v2.Asset import com.axeda.services.v2.ExecutionResult import groovy.json.JsonSlurper import net.sf.json.JSONObject import groovy.xml.MarkupBuilder /** * ConfigItem_CRU.groovy * ----------------------- * * Reads in json from an http post request and reads, adds, deletes or updates Configuration Items. * * * @note this parses a post and does not take any additional parameters. * * @author sara streeter <sstreeter@axeda.com> */ def contentType = "application/json" final def serviceName = "ConfigItem_CRU" def response = [:] def writer = new StringWriter() def xml = new MarkupBuilder(writer) try { // BUSINESS LOGIC BEGIN def assetId def validationOnly def validationResponse = "" List<ConfigurationItem> configItemList if (Request?.body != null && Request?.body !="") { def slurper = new JsonSlurper() def request = slurper.parseText(Request?.body) assetId = request.result.assetId validationOnly = request.result.validationOnly?.toBoolean() if (request.result.items != null && request.result.items.size() > 0){ configItemList = request.result.items.inject([]) { target, item -> if (item && item.path != "" && item.key != "" && item.path != null && item.key != null){ ConfigurationItem configItem = new ConfigurationItem() configItem.path = item.path + item.key configItem.value = item.value target << configItem } target } } } if (assetId != null) { def asset = assetBridge.find([assetId])[0] AssetConfiguration config = assetConfigurationBridge.getAssetConfiguration(assetId, "") def itemToDelete if (config == null) { createConfigXML(xml) AssetConfiguration configToCreate = assetConfigurationBridge.fromXml(writer.toString(), asset.id) ExecutionResult result = assetConfigurationBridge.create(configToCreate) AssetConfiguration config2 = assetConfigurationBridge.getAssetConfiguration(asset.id, "") config = config2 itemToDelete = "/Item" } if (configItemList != null && configItemList?.size() > 0){ List<ConfigurationItem> compareList = config.items def intersectingCompareItems = compareList.inject(["save": [], "delete": []]) { map, item -> // find whether to delete def foundItem = configItemList.findAll{ compare -> item?.path == compare?.path && item?.value == compare?.value } map[foundItem.size() > 0 ? "save" : "delete"] << item map } intersectingCompareItems.delete = intersectingCompareItems.delete.collect{it.path} if (itemToDelete){ intersectingCompareItems.delete.add(itemToDelete) } def intersectingConfigItems = configItemList.inject(["old": [], "new": []]) { map, item -> // find whether it's old def foundItem = compareList.findAll{ compare -> item?.path == compare?.path && item?.value == compare?.value } map[foundItem.size() > 0 ? "old" : "new"] << item map } assetConfigurationBridge.deleteConfigurationItems(config, intersectingCompareItems.delete) assetConfigurationBridge.appendConfigurationItems(config, intersectingConfigItems.new) def exResult = assetConfigurationBridge.validate(config) if (exResult.successful){ validationResponse = "success" if (!validationOnly){ assetConfigurationBridge.update(config) } } else { validationResponse = exResult.failures[0]?.details } } response = [ assetId: assetId, items: config?.items?.collect { item -> def origpath = item.path def lastSlash = origpath.lastIndexOf("/") def key = origpath.substring(lastSlash + 1, origpath.length()) def path = origpath.replace("/" + key, "") path += "/" [ path: path, key: key, value: item.value ] }, validationResponse: validationResponse ] } else { throw new Exception("Error: Asset Id must be provided.") } } catch (Exception ex) { logger.error ex response = [ error: [ type: "Backend Application Error" , msg: ex.getLocalizedMessage() ] ] } return ['Content-Type': 'application/json', 'Content': JSONObject.fromObject(response).toString(2)] /** * Create the Success response. * * @param xml : The xml response.<br> * @param info : If this is set to "1" the info element will be included in the response.<br> * @param infos : Collection of information to include within the info element of the response.<br> */ private void createConfigXML(xml) { xml.Item() }

May 12, 2016

This script illustrates how to call a Groovy script as an external web service. This example also applies to calling any external web service that relies on a username and password. Parameters: external_username external_password script_name import com.axeda.drm.sdk.Context import com.axeda.drm.sdk.device.DeviceFinder import com.axeda.drm.sdk.data.CurrentDataFinder import com.axeda.drm.sdk.device.Device import com.axeda.drm.sdk.data.HistoricalDataFinder import com.axeda.drm.sdk.device.DataItem import net.sf.json.JSONObject import com.axeda.drm.sdk.device.ModelFinder import groovyx.net.http.* import static groovyx.net.http.ContentType.* import static groovyx.net.http.Method.* /** * CallScriptoAsExternalWebService.groovy * * This script illustrates how to call a Groovy script as an external web service. * * @param external_username - (REQ):Str Username for the external web service. * @param external_password - (REQ):Str Password for the external web service. * @param script_name - (REQ):Str Script Name to call. * * */ def result try { validateParameters(actual: parameters, expected: ["external_username", "external_password", "script_name"]) // authentication tokens (username + password) def auth_tokens = [username: parameters.external_username, password: parameters.external_password] http = new HTTPBuilder( 'http://platform.axeda.com/services/v1/rest/Scripto/execute/'+parameters.script_name ) // pass in dummy parameters to the script for illustration def parammap = [key1: "val1", key2: "val2"] // Call the script http.request (GET, JSON) { uri.query = auth_tokens + parammap response.success = { resp, json -> // traverse the wrapped json response result = json.wsScriptoExecuteResponse.content.$ } response.failure = { resp -> result = response.failure } } } catch (Throwable any) { logger.error any.localizedMessage } return ['Content-Type': 'application/json', 'Content': result] static def validateParameters(Map args) { if (!args.containsKey("actual")) { throw new Exception("validateParameters(args) requires 'actual' key.") } if (!args.containsKey("expected")) { throw new Exception("validateParameters(args) requires 'expected' key.") } def config = [ require_username: false ] Map actualParameters = args.actual.clone() as Map List expectedParameters = args.expected config.each { key, value -> if (args.options?.containsKey(key)) { config[key] = args.options[key] } } if (!config.require_username) { actualParameters.remove("username") } expectedParameters.each { paramName -> if (!actualParameters.containsKey(paramName) || !actualParameters[paramName]) { throw new IllegalArgumentException( "Parameter '${paramName}' was not found in the query; '${paramName}' is a reqd. parameter.") } } }

May 10, 2016

Calling external services from M2M applications is a critical aspect of building end-to-end solutions. Knowing how to apply network timeouts when connecting to external servers can prevent unexpected and problematic network hang-ups. Let's investigate how to create a safe networking flow using HttpClient, HttpBuilder, and Apache’s FTPClient class. Background Custom Objects called from Expression Rules have a configurable maximum execution time. This is set by the com.axeda.drm.rules.statistics.rule-time-threshold property. Without this safeguard in place long running or misbehaved Custom Objects can cause internal processing queues to fill and the server will suffer a performance degradation. In Java (and Groovy) all network calls internally use InputStream.read() to establish the socket connection and to read data from the socket. It is possible for faulty external servers (such as an FTP server) to hang and not properly respond. This means that the InputStream.read() method will continuously wait for the server to respond with data, and the server will never respond. According to the Java spec, InputStream.read() may be uninterruptable while it is waiting for data. This means that if a Custom Object has exceeded the com.axeda.drm.rules.statistics.rule-time-threshold the Rule Sniper will still not be able to interrupt the Custom Object’s execution if it is waiting on InputStream.read(). Because the Custom Object cannot be stopped, the internal processing queues will eventually fill. Even though InputStream.read() is uninterruptable it is still possible to set timeouts for it to be able to give up on a connection. Beyond that, we want to make sure that the connection is completely disconnected. Types of Timeouts There are typically two types of timeouts that should be set when making calls over the web: the Connection Timeout and the Socket Timeout. The Connection Timeout is the maximum amount of time that should be allowed when establishing the bi-directional socket connection between the client and server. Behind the scenes socket connection involves resolving the domain name of the server to an IP address, and then the server opening a port to connect with the client’s port. The Socket Timeout is the timeout that limits the amount of time each socket operation is allowed to take. It limits the amount of time InputStream.read() will listen for a server’s response. If a server is faulty or overloaded it may take a long time (or forever) to respond to a request. This timeout limits the amount of time the client will wait for the server to respond. When making any calls from a Custom Object to an external server (either making WebService calls, or FTP transfers), you should always set the Connection Timeout and the Socket Timeout. Always try to keep the timeouts as reasonably small as possible. Failure to do so could unexpectedly impact your Axeda server. Consider a Custom Object that takes an average of 10 seconds to run is called to make an external WebService call once a minute. This will not cause any issues and the system will be stable. If the external server suddenly has a performance degredation and now the external WebService call takes over a minute to run, the execution queue will eventually fill, causing performance degradation to the Axeda system. To protect against this scenario, set the timeouts to limit the call to one minute, and log whenever the time limit is exceeded. Examples Provided below are examples of properly set timeouts and thorough connection management use HttpClient, HttpBuilder, and FTPClient. All of these examples assume they are being executed from Custom Objects. By default, set the Connection Timeout to 10 seconds. In normal circumstances, connections should not take more then 10 seconds. If they are exceeding this time there is a good chance of networking issues between the client and server. The Socket Timeout can vary per use-case. The examples provided set the Socket Timeout to 30 seconds, which should be sufficient for typical WebService calls and small to medium sized FTP file transfers. Depending exactly on what is being done, the timout may have to be increased. If you expect the call to go over 5 minutes please contact Axeda Support to investigate increasing com.axeda.drm.rules.statistics.rule-time-threshold property (which defaults to 5 minutes). HttpClient //HttpClient import org.apache.http.client.HttpClient import org.apache.http.impl.client.DefaultHttpClient import org.apache.http.client.methods.HttpGet import org.apache.http.HttpResponse import org.apache.http.params.BasicHttpParams import org.apache.http.params.HttpParams import org.apache.http.params.HttpConnectionParams int TENSECONDS = 10*1000 int THIRTYSECONDS = 30*1000 final HttpParams httpParams = new BasicHttpParams() //Establishing the connection should take <10 seconds in most circumstances HttpConnectionParams.setConnectionTimeout(httpParams, TENSECONDS) //The data transfer/call should take <30 seconds. Adjust as necessary if receiving large data sets. HttpConnectionParams.setSoTimeout(httpParams, THIRTYSECONDS) HttpClient hc = new DefaultHttpClient(httpParams) try { //Simply get the contents of http://www.axeda.com and log it to the Custom Object Log HttpGet get = new HttpGet("http://www.axeda.com") HttpResponse response = hc.execute(get) BufferedReader br = new BufferedReader( new InputStreamReader( response.getEntity().getContent())) br.readLines().each { logger.info it } } finally { //Make sure to shutdown the connectionManager hc.getConnectionManager().shutdown() } return true https://gist.github.com/axeda/5189092/raw/2f7b93c5f96ed8f445df4364b885486bc6fa1feb/HttpClientTimeouts.groovy HttpBuilder import groovyx.net.http.HTTPBuilder import static groovyx.net.http.ContentType.* import static groovyx.net.http.Method.* int TENSECONDS = 10*1000; int THIRTYSECONDS = 30*1000; HTTPBuilder builder = new HTTPBuilder('http://www.axeda.com') //HTTPBuilder has no direct methods to add timeouts. We have to add them to the HttpParams of the underlying HttpClient builder.getClient().getParams().setParameter("http.connection.timeout", new Integer(TENSECONDS)) builder.getClient().getParams().setParameter("http.socket.timeout", new Integer(THIRTYSECONDS)) try { //Simply get the contents of http://www.axeda.com and log it to the Custom Object Log builder.request(GET, TEXT){ response.success = { resp, res -> res.readLines().each { logger.info it } } } } finally { //Make sure to always shut down the HTTPBuilder when you’re done with it builder.shutdown() } return true https://gist.github.com/axeda/5189102/raw/66bb3a4f4f096681847de1d2d38971e6293c4c6b/HttpBuilderTimeouts.groovy FtpClient Apache’s FTPClient has a third type of timeout, the Default Timeout. The Default Timeout is a timeout that further ensures that socket timeouts are always used. Note: Default Timeout does not set a timeout for the .connect() method. import org.apache.commons.net.ftp.* import java.io.InputStream import java.io.ByteArrayInputStream String ftphost = "127.0.0.1" String ftpuser = "test" String ftppwd = "test" int ftpport = 21 String ftpDir = "tmp/FTP" int TENSECONDS = 10*1000 int THIRTYSECONDS = 30*1000 //Declare FTP client FTPClient ftp = new FTPClient() try { ftp.setConnectTimeout(TENSECONDS) ftp.setDefaultTimeout(TENSECONDS) ftp.connect(ftphost, ftpport) //30 seconds to log on. Also 30 seconds to change to working directory. ftp.setSoTimeout(THIRTYSECONDS) def reply = ftp.getReplyCode() if (!FTPReply.isPositiveCompletion(reply)) { throw new Exception("Unable to connect to FTP server") } if (!ftp.login(ftpuser, ftppwd)) { throw new Exception("Unable to login to FTP server") } if (!ftp.changeWorkingDirectory(ftpDir)) { throw new Exception("Unable to change working directory on FTP server") } //Change the timeout here for a large file transfer that will take over 30 seconds //ftp.setSoTimeout(THIRTYSECONDS); ftp.setFileType(FTPClient.ASCII_FILE_TYPE) ftp.enterLocalPassiveMode() String filetxt = "Some String file content" InputStream is = new ByteArrayInputStream(filetxt.getBytes('US-ASCII')) try { if (!ftp.storeFile("myFile.txt", is)) { throw new Exception("Unable to write file to FTP server") } } finally { //Make sure to always close the inputStream is.close() } } catch(Exception e) { //handle exceptions here by logging or auditing } finally { //if the IO is timed out or force disconnected, exceptions may be thrown when trying to logout/disconnect try { //10 seconds to log off. Also 10 seconds to disconnect. ftp.setSoTimeout(TENSECONDS); ftp.logout(); //depending on the state of the server the .logout() may throw an exception, //we want to ensure complete disconnect. } catch(Exception innerException) { //You potentially just want to log that there was a logout exception. } finally { //Make sure to always disconnect. If not, there is a chance you will leave hanging sockects ftp.disconnect(); } } return true https://gist.github.com/axeda/5189120/raw/83545305a38d03b6a73a80fbf4999be3d6b3e74e/FtpClientConnectionTimeouts.groovy

May 10, 2016

This script creates a csv file from the audit log filtered by the User Access category, so dates of when users logged in or logged out. *** see update below *** Note: The csv file has the same name as the Groovy script and does NOT have the .csv extension . To get the .csv extension, the Groovy script has to be renamed to AuditEntryToCSV.csv.groovy . Suggestions on how to improve this are welcome. *** Update ***: The download works without the renamed groovy script by returning text instead of an input stream. The script has been modified to illustrate this. Parameters: days - the number of days past to fetch audit logs model_name - the model name of the asset serial_number - the serial number of the asset import com.axeda.drm.sdk.device.ModelFinder import com.axeda.drm.sdk.Context import com.axeda.common.sdk.id.Identifier import com.axeda.drm.sdk.device.Model import com.axeda.drm.sdk.device.DeviceFinder import com.axeda.drm.sdk.device.Device import com.axeda.drm.sdk.audit.AuditCategoryList import com.axeda.drm.sdk.audit.AuditCategory import com.axeda.drm.sdk.audit.AuditEntryFinder import com.axeda.drm.sdk.audit.SortType import com.axeda.drm.sdk.audit.AuditEntry import groovy.xml.MarkupBuilder import com.axeda.platform.sdk.v1.services.ServiceFactory /* * AuditEntryToCSV.groovy * * Creates a csv file from the audit log filtered by the User Access category, so dates of when users logged in or logged out. * * @param days - (REQ):Str number of days to search. * @param model_name - (REQ):Str name of the model. * @param serial_number - (REQ):Str serial number of the device. * * @note - the csv file has the same name as the Groovy script and does NOT have the .csv extension . To get * the .csv extension, the Groovy script has to be renamed to AuditEntryToCSV.csv.groovy . * * @author Sara Streeter <sstreeter@axeda.com> */ def writer = new StringWriter() def xml = new MarkupBuilder(writer) try { def ctx = Context.getUserContext() ModelFinder modelFinder = new ModelFinder(ctx) modelFinder.setName(parameters.model_name) Model model = modelFinder.find() DeviceFinder deviceFinder = new DeviceFinder(ctx) deviceFinder.setSerialNumber(parameters.serial_number) Device device = deviceFinder.find() AuditCategoryList acl = new AuditCategoryList() acl.add(AuditCategory.USER_ACCESS) long now = System.currentTimeMillis() Date today = new Date(now) def paramdays = parameters.days ? parameters.days: 5 long days = 1000 * 60 * 60 * 24 * Integer.valueOf(paramdays) AuditEntryFinder aef = new AuditEntryFinder(ctx) aef.setCategories(acl) aef.setToDate(today) aef.setFromDate(new Date(now - (days))) aef.setSortType(SortType.DATE) aef.sortDescending() List<AuditEntry> audits = aef.findAll() // use a Data Accumulator to store the information def dataStoreIdentifier = "FILE-CSV-audit_log" def daSvc = new ServiceFactory().dataAccumulatorService if (daSvc.doesAccumulationExist(dataStoreIdentifier, device.id.value)) { daSvc.deleteAccumulation(dataStoreIdentifier, device.id.value) } // assemble the response audits.each { AuditEntry audit -> def row = [ audit?.id.value, audit?.user?.username, audit?.date, audit?.category?.bundleKey, audit?.message ] row = row.join(',') row += '\n' daSvc.writeChunk(dataStoreIdentifier, device.id.value, row); } // stream the data accumulator to create the file InputStream is = daSvc.streamAccumulation(dataStoreIdentifier, device.id.value) return ['Content-Type': 'text/csv', 'Content-Disposition':'attachment; filename=AuditEntryCSVFile.csv', 'Content': is.text] } catch (def ex) { xml.Response() { Fault { Code('Groovy Exception') Message(ex.getMessage()) StringWriter sw = new StringWriter(); PrintWriter pw = new PrintWriter(sw); ex.printStackTrace(pw); Detail(sw.toString()) } } logger.info(writer.toString()) }

May 10, 2016

IoT Tips

Axeda: Finding current and historical Dataitems for all Assets in a Model

Axeda: Emailing an Attachment

Content Types Returned from Axeda Scripto

Best Practices for Managing Data in Axeda

Axeda Data Model

Axeda Connectivity Using AMMP Toolkits

Guard Rails on the Axeda Platform

Axeda Audits, Logging and Reports

Axeda Sample Application: Starter Custom Tab

Extending the Axeda Platform UI - Custom Tabs and Modules

Axeda Scripto Editor

Using the Edge MicroServer and LSR in a Gateway Scenario

Axeda: Email File From Data Accumulator

Axeda: Create and then delete a data item on a model

Frequently Seen Errors upon launching the ThingWorx application:

Getting started with Axeda AMMP

Convert Data Item Timestamp to Different Timezone

Axeda Connected Configuration Items Create/Read/Update

Calling a Groovy script as an External Web Service

Axeda: Applying Timeouts when calling Web Services and FTP from Custom Objects

Audit Entry to CSV

ThingWorx Learning Paths

Getting Started on the ThingWorx Platform Learning Path