Using Axeda Scripto

[#1]

Scripto provides a RESTful endpoint for Groovy Custom Objects on the Axeda Platform.  Custom Objects exposed via Scripto can be accessed via a GET or a POST, and the script will have access to request parameters or body contents. Any Custom Object of the "Action" type will automatically be exposed via Scripto. The URL for a Scripto service is currently defined by the name of the Custom Object:

GET: http://{{YourHostName}}/services/v1/rest/Scripto/execute/<customObjectName>

Scripto enables the creation of "Domain Specific Services". This allows implementers to take the Axeda Domain Objects (Assets, Models, DataItems, Alarms) and expose them via a service that models the real-world domain directly (trucks, ATMs, MRI Machines, sensor readings). This is especially useful when creating a domain-specific UI, or when integrating with another application that will push or pull data.

Authentication

There are several ways to test your Scripto scripts, as well as several different authentication methods. The following authentication methods can be used:

Request Parameter credentials: ?username=<yourUserName>&password=<yourPassword>

Request Parameter sessionId (retrieved from the Auth service): ?sessionid=<sessionId>

Basic Authentication (challenge): From a browser or CURL, simply browse to the URL to receive an HTTP Basic challenge.

Request Parameters

You can access the parameters to the Groovy script via two Objects, Call and Request. Request is actually just a sub-class of Call, so the values will always be the same regardless of which Object you use.  Although parameters may be accessed off of either object, Call is preferable when Chaining Custom Objects (TODO LINK) together.  Call also includes a reference to the logger which can be used to log debug messages.

GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>?sessionid=<Session Id>&serial_number=mySerialNumber

Accessing Parameters through the Request Object

import com.axeda.drm.sdk.scripto.Request
// Request.parameters is a map of strings
def serial_number = Request.parameters.serial_number
assert serial_number == "mySerialNumber"
      

Accessing Parameters through the Call Object

import com.axeda.drm.sdk.customobject.Call
// Call.parameters is a map of strings
def serial_number = Call.parameters.serial_number
assert serial_number == "mySerialNumber"
      

Accessing the POST Body through the Request Object

The content from a POST request to Scripto is accessible as a string via the body field in the Request object.  Use Slurpers for XML or JSON to parse it into an object.

POST:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>?sessionid=<Session Id>

Response: { "serial_number":"mySerialNumber"}

import com.axeda.drm.sdk.scripto.Request
def body = Request.body
def slurper = new JsonSlurper()
def result = slurper.parseText(body)
assert result.serial_number == "mySerialNumber"
      

Returning Plain Text

Groovy custom objects must return some content.  The format of that content is flexible and can be returned as plain text, JSON, XML, or even binary files. The follow example simply returns plain text.

GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>

// Outputs:  hello
return ["Content-Type":"text/plain","Content":"hello"]
      

Returning JSON

We use the JSONObject Class to format our Map-based content into a JSON structure. The eliminates the need for any concern around formatting, you just build up Maps of Maps and it will be properly formatted by the fromObject() utility method.

GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>

import net.sf.json.JSONObject
root = [
  items:[    num_1: “one”,    num_2: “two”            ]
]
/** Outputs
{
  "items": {  "num_1": "one", "num_2": "two"  }
}
**/
return ['Content-Type': 'application/json', 'Content': JSONObject.fromObject(root).toString(2)]
      

Link to JSONObject documentation

Returning XML

To return XML, we use the MarkupBuilder to build the XML response. This allows us to create code that follows the format of the XML that is being generated.

GET:  http://{{YourHostName}}/services/v1/rest/Scripto/execute/<Your Script Name>?sessionid=<Session Id>

import groovy.xml.MarkupBuilder
def writer = new StringWriter()
def xml = new MarkupBuilder(writer)
xml.root(){
    items(){
        num_1("one")
        num_2("two")
    }
}
/** Outputs
<root>
  <items>
    <num_1>one</num_1>
    <num_2>two</num_2>
  </items>
</root>
**/
return ['Content-Type': 'text/xml', 'Content': writer.toString()]
      

Link to Groovy MarkupBuilder documentation

Returning Binary Content

To return binary content, you typically will use the fileStore API to upload a file that you can then download using Scripto.  See the fileInfo section to learn more. In this example we connect the InputStream which is associated with the getFileData() method directly to the output of the Scripto script. This will cause the bytes available in the stream to be directly forwarded to the client as the body of the response.

GET:  http://{{Your Host Name}}/services/v1/rest/Scripto/execute/{{Your Script Name}}?sessionid={{Session Id}}&fileId=123

import static com.axeda.sdk.v2.dsl.Bridges.*
import com.axeda.services.v2.*
import com.axeda.sdk.v2.exception.*
def contentType = parameters.type ?: 'image/jpg'
return ['Content':fileInfoBridge.getFileData(parameters.fileId), 'Content-Type':contentType]
  

The Auth Service - Authentication via AJAX

Groovy scripts are accessible to AJAX-powered HTML apps with Axeda instance credentials.  To obtain a session from an Axeda server, you should make a GET call to the Authentication service. The service is located at the following example URL:

https://{{YourHostName}}/services/v1/rest/Auth/login

This service accepts a valid username/password combination in the incoming Request parameters and returns a SessionID. The parameter names it expects to see are as follows:

Property Name	Description
principal.username	The username for the valid Axeda credential.
password	The password for the supplied credential.

A sample request to the Auth Service:

GET: https://{{YourHostName}}/services/v1/rest/Auth/login?principal.username=YOURUSER&password=YOURPASS

Would yield this response (at this time the response is always in XML):

<ns1:WSSessionInfo xsi:type="ns1:WSSessionInfo" xmlns:ns1="http://type.v1.webservices.sl.axeda.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ns1:created>2013-08-12T13:19:37 +0000</ns1:created>
  <ns1:expired>false</ns1:expired>
  <ns1:sessionId>19c33190-dded-4655-b2c0-921528f7b873</ns1:sessionId>
<ns1:sessionTimeout>
1800
</ns1:sessionTimeout>
</ns1:WSSessionInfo>
      

The response fields are as follows:

Field Name	Description
created	The timestamp for the date the session was created
expired	A boolean indicating whether or not this session is expired (should be false)
sessionId	The ID of the session which you will use in subsequent requests
sessionTimeout	The time (in seconds) that this session will remain active for

The Auth Service is frequently invoked from JavaScript as part of Custom Applications. The following code demonstrates this style of invocation.

function authenticate(host, username, password) {
            try {
                netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");
            } catch (e) {
                // must be IE
            }
            var xmlHttpReq = false;
            var self = this;
            // Mozilla/Safari
            if (window.XMLHttpRequest) {
                self.xmlHttpReq = new XMLHttpRequest();
            }
            // IE
            else if (window.ActiveXObject) {
                self.xmlHttpReq = new ActiveXObject("Microsoft.XMLHTTP");
            }
            var SERVICES_PATH = "/services/v1/rest/"
            var url = host + SERVICES_PATH + "Auth/login?principal.username=" + username + "&password=" + password;
            self.xmlHttpReq.open('GET', url, true);
            self.xmlHttpReq.onreadystatechange = function() {
                if (self.xmlHttpReq.readyState == 4) {
                    getSessionId(self.xmlHttpReq.responseXML);
                }
            }
            self.xmlHttpReq.send()
}
function getSessionId(xml) {
            var value
            if (window.ActiveXObject) {
                // xml traversing with IE
                var objXML = new ActiveXObject("MSXML2.DOMDocument.6.0");
                objXML.async = false;
                var xmldoc = objXML.loadXML(xml);
                objXML.setProperty("SelectionNamespaces", "xmlns:ns1='http://type.v1.webservices.sl.axeda.com'");
                objXML.setProperty("SelectionLanguage","XPath");
                value =  objXML.selectSingleNode("//ns1:sessionId").childNodes[0].nodeValue;
            } else {
                // xml traversing in non-IE browsers
                var node = xml.getElementsByTagNameNS("*", "sessionId")
                value = node[0].textContent
            }
            return value
}
authenticate ("http://mydomain.axeda.com", "myUsername", "myPassword")
      

Calling Scripto via AJAX

Once you have obtained a session id through authentication via AJAX, you can use that session id in Scripto calls. The following is a utility function which is frequently used to wrap Scripto invocations from a UI.

function callScripto(host, scriptName, sessionId, parameter) {
            try {
                netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");
            } catch (e) {
                // must be IE
            }
            var xmlHttpReq = false;
            var self = this;
            // Mozilla/Safari
            if (window.XMLHttpRequest) {
                self.xmlHttpReq = new XMLHttpRequest();
            }
            // IE
            else if (window.ActiveXObject) {
                self.xmlHttpReq = new ActiveXObject("Microsoft.XMLHTTP");
            }
            var url = host + SERVICES_PATH + "Scripto/execute/" + scriptName + "?sessionid=" + sessionId;
            self.xmlHttpReq.open('GET', url, true);
            self.xmlHttpReq.onreadystatechange = function() {
                if (self.xmlHttpReq.readyState == 4) {
                    updatepage(div, self.xmlHttpReq.responseText);
                }
            }
            self.xmlHttpReq.send(parameter);
}
function updatepage(div, str) {
            document.getElementById(div).innerHTML = str;
}
callScripto("http://mydomain.axeda.com", "myGroovyScriptName", "mySessionId", "myparameter=foo")
      

A more modern jQuery-based example might look like the following:

function callScripto(host, scriptName, sessionId, parameter) {
    var url = host + '/services/v1/rest/Scripto/execute/' + scriptName + '?sessionid=' + sessionId
    if ( parameter != null ) url += '&' + parameter
    $.ajax({url: url,
              success:  function(response) {  updatepage(div, response); }
          });
}
function updatepage(div, str) {
    $("#" + div).innerHTML = str
}
callScripto("http://mydomain.axeda.com", "myGroovyScriptName", "mySessionId", "myparameter=foo")
 

In Conclusion

As shown above, Scripto offers a number of ways to interact with the platform.  On each version of the Axeda Platform, all supported v1 and v2 APIs are available for Scripto to interact with the Axeda domain objects and implement business logic to solve real-world customer problems.

Bibliography ​(PTC.net account required)

    Axeda v2 API/Services Developer's Reference Version 6.8.3 August 2015

    Axeda® v1 API Developer’s Reference Guide Version 6.8 August 2014

    Documentation Map for Axeda® 6.8.2 January 2015