Building a "HelloWorld" WebService with Scripto

Scripto Overview

Scripto is an Axeda Platform feature that allows you to implement a domain-specific Web Service API for your solution, completely in the cloud. In this way, your application developers or business partners can consume an API that is specific to your domain.

While the Axeda Platform provides a comprehensive API for accessing foundational domain objects and data, implementing a solution, or domain-specific API makes the implementation of your solution more natural and expressive within your domain.

For example, if your solution is about tracking vehicles, you may design an API with high-level operations such as GetVehicleList, SetDriverPreferences, CreateAlertOnGeoEntry, etc. Note that the Axeda Platform does not know what these operations mean - only you do. You can use Scripto to implement these high-level workflows in Custom Objects which then use the foundational SDK to carry out the work.

Scripto is an Axeda Web Service that lets you execute scripts (Custom Objects) that you have written using the Platform. The "wrapper" interface around Scripto can be invoked REST-style or via SOAP, and specifies only the name of the script to execute and parameters for it. In this way, semantics of the operation are completely at your control.

Mechanics

In order to execute the scripts, the Web Service needs the user context to run the script. The WebService needs to know that the user executing the Groovy script is an authenticated Platform user, so a session Id is passed to the WebServices which is an Id based on a user/password combination. 

There are different ways in which you can execute the script. The first way is using the Platform UI.

Configure and Test Groovy scripts on the Platform UI

Navigate to the Configuration Tab

 

Click on New -> Custom Object

 

Enter Name = “HelloWorld”
Type = “Action”
Description = Optional
Source = <paste source code here>
 
                      def result = "Hello ${parameters.foo}"
                      logger.info(result.toString())
                     return ['Content-Type': 'text/plain', 'Content':  result.toString()] 

  
 
Configuring a parameter:

 

Add the variable and Save Changes

 
Compiling your script:

Click on the Compile button and make sure there are no errors (please note a popup window will be displayed with the compilation results, so make sure to enable the popup for this page)

 

Good, there were no errors or warnings, so close the Compilation results window and click the Next >> button

 
Testing your “HelloWorld” script

In this step, we are going to test the Script output:

In the Asset Serial Number area, type in any of your assets.

Enter a string for the foo variable e.g. “World” and click the Test button (The test results will open a new popup window)

 

Click the Close button and the Finish button and then Finish again to commit the Script

Testing Scripto from the Command Line

The next way to test Scripto is via the command line.

If you do not have it, you will need to install CURL from http://curl.haxx.se/.  On Windows, unpack the folder, rename it to 'Curl' and copy it to C:\Program Files.  You will need to add C:\Program Files\Curl to your path. 

Login

The first step is to call Auth to Obtain a Sessionid:

C:\> curl "http://dev6.axeda.com/services/v1/rest/Auth/login?principal.username=[your user]&password=[your password]"

This Web Service returns the sessionid based on your given user and password (example highlighted below)

<?xml version='1.0' encoding='UTF-8'?>
<ns1:WSSessionInfo xmlns:ns1="http://type.v1.webservices.sl.axeda.com" xmlns:ns2="http://www.w3.org/2001/XMLSchema-instance" ns2:type="ns1:WSSessionInfo">
<ns1:created>2010-11-24T15:13:19 +0000</ns1:created>
<ns1:expired>false</ns1:expired>
<ns1:sessionId>OAk4LIf-LJ+9X-LXOVVVNGNcuLexZON43qlNPAc5py3-3jllS2nf</ns1:sessionId>
<ns1:sessionTimeout>1800</ns1:sessionTimeout>
</ns1:WSSessionInfo>

 Execute Script 

Here you are using your sessionid and passing it to the script.

C:\ curl "http://dev6.axeda.com/services/v1/rest/Scripto/execute/HelloWorld?sessionid=[sessionid from login]" -d "foo=World"

URL = http://dev6.axeda.com/services/v1/rest/Scripto/execute
HelloWorld = Groovy Script to run
sessionid = user session created in above step
"foo=World" = parameter passed to Script (foo is parameter: World  is the value)

Logout

The logout REST call will invalidate the user session bypassing the sessionid

C:\> curl "http://dev6.axeda.com/services/v1/rest/Auth/logout?sessionid=[sessionid from login]"

You've just completed your first scripting tutorial!

Resources

The next tutorial shows you how to call a script from a web page using Javascript and dynamic page updating.

Or you can check out other Scripto examples.

Keywords: