Requirements: Axeda 6.1.6+
While we think the power of scripting applications in the Axeda platform delivers a great way to build M2M solutions, we also understand the rigors of professional software development. That's why we've created Axeda Artisan, a system for developing Axeda Custom Objects and RIA applications in the familiar, robust environment you are used to and for publishing directly to the Axeda Platform.
NOTE: For developers using Axeda Version 6.6, documentation on Artisan for Axeda 6.6 is available at Artisan Overview (v6.6.0)
What this tutorial covers
1) Artisan Goals - why use Artisan
2) Artisan Dependencies - steps to take before you can use Artisan
3) Artisan Project Set Up - set up your first Artisan project
4) Configuration File - configuring the Artisan project with apcmetadata.xml
5) Upload the Project - upload the Artisan project using Maven
· Provide a project structure for keeping Custom Object scripts and RIA code together in a cohesive project
· Layout a project in a file system structure that is natural for SCM tools like Subversion and GIT, so developers can maintain source code control over their projects
· Provide a deployment system so that a project's scripts and RIA apps can be uploaded to the Axeda Platform in a single command, without needing to log into the Platform Administration UI
· Use a modern IDE with superior Groovy language support, and access to the Axeda SDK class stubs for code-completion
· Automatic distribution of Axeda SDK stub classes via Apache Maven – no need to go looking for the latest SDK and documentation.
Edit Axeda Custom Objects for Rules or Scripto in an advanced, modern IDE with Groovy language support and the Axeda SDK classes available for quick documentation lookup and code-completion.
A thoughtful project structure to keep your UI code and Custom Objects together in one place.
You can use an IDE, but there’s no need to. Artisan uses Apache Maven to maintain dependencies and to impose project structure. You can do it all from a command line if you like.
Single command to push your custom objects and RIA to your Axeda Platform account.
(note, all tools mentioned below are cross platform and should work great on Windows, Mac, and Linux. Screenshots below are from Mac OSX, but apply for Windows and Linux)
- Register an account on developer.axeda.com if you haven't already done so. http://developer.axeda.com/user/register
- Download and install the Java 6 Development Kit from http://www.oracle.com/technetwork/java/javase/downloads/jdk6-jsp-136632.html .
- *NOTE: Make sure your JAVA_HOME environment variable set correctly. The JDK installer should do this but you can verify by following these steps: http://download.oracle.com/docs/cd/E19182-01/820-7851/inst_cli_jdk_javah.... Also make sure JAVA_HOME is on your PATH.
- Install and configure Maven 2.2.1: http://maven.apache.org/download.html , http://maven.apache.org/run-maven/index.html
- *NOTE: Make sure the M2 and M2_HOME environment variables are set up correctly, as per the install instructions for Maven. Also make sure Maven is on your PATH.
- Install IntelliJ IDEA 10 community Edition: http://www.jetbrains.com/idea/download/
or Eclipse: http://www.eclipse.org/
- Download Axeda Artisan Starter project at http://developer.axeda.com/artisan-starter-1-download or the Artisan SDKv2 project (works with Axeda 6.5 and above) artisan_sdkv2.zip . If you are converting a pre-SDKv2 project to work with Axeda 6.5, please see the instructions at the end of the article.
Unzip the artisan-starter.zip to your local development system. You should end up with the following directory structure
│ └── src
│ └── main
│ ├── assembly
│ └── webapp
│ ├── images
│ ├── scripts
│ └── styles
│ ├── groovy
│ └── resources
Open IntelliJ and select File->Open Project. Browse to your artisan-starter directory and select the file pom.xml which is at the root of the project directory. The IntelliJ screen will look blank, but you can now expand the Project pane at the top left of the window.
At this point, IntelliJ has read the Maven project structure and automatically downloaded the dependent libraries, including the Axeda SDK, to your local Maven repository, and made them part of your IntelliJ project. You may now begin editing Groovy scripts with code-completion.
Please note: If you are an Axeda customer and have your own instance of the Axeda Platform, please follow these steps so that Artisan project is using the correct Axeda SDK.
1. Click on the pom.xml under artisan-starter-scripts
2. You will need to replace the version parameter with your Axeda Platform version
You can find your version of the Axeda Platform by logging into the platform UI, and clicking on the About link
Find the following section and replace the version
Please note :
Axeda ServiceLink Summer '11 Release -> 6.1.3
Axeda ServiceLink Fall '11 Release -> 6.1.4
Axeda ServiceLink Winter '12 Release -> 6.1.5
Axeda ServiceLink Spring '12 Release -> 6.1.6
Please note that IntelliJ does not always resolve the classes after this change, so a restart of the IDE will fix it.
Let’s try that out.
Using the IntelliJ project explorer, navigate to /artisan-starter-scripts/src/main/groovy/GetChartData.groovy and double-click to open.
Try changing some code and notice that the Axeda SDK classes show code completion. Nice, eh? Be sure to undo any edits.
Axeda Platform Javadocs are also available. In IntelliJ, click on the Maven Projects tab and expand Axeda Artisan Starter Scripts/Dependencies. Right-click com.axeda:platform-sdk:6.1.2W and select Download Documentation.
Now, back in GetChartData.groovy, place your cursor within the class identifier HistoricalDataFinder on line 38, and press CTRL+Q (CTRL+J on Mac) for Quick Documentation Lookup. You may also press SHIFT+F1 to instruct IntelliJ to open the Javadocs in a full web browser view.
Now open the file apc-metadata.xml. This file tells the Artisan installer which Groovy files to upload, and how to configure them in the Axeda platform. Notice the section that describes GetChartData.
To create more Custom Objects, just add Groovy Script files to artisan-starter-scripts/src/main/groovy/ and then add some XML in apc-metadata.xml to describe it.
An apc-metadata.xml file starts off with:
<?xml version="1.0" encoding="UTF-8"?>
<apcmetadata version="1.0.0" project="MyCustomApp">
Here's how the xml looks for the various objects you can add:
Models with data items
<!--standalone or gateway-->
<!--string or digital or analog-->
<!--0 = no history,1 = Stored,2 = no storage,3 = on change-->
Custom Objects with Parameters
<param name="parameter_name" description="(REQUIRED) Str - Parameter Description"/>
<description>Expression Rule Description</description>
<![CDATA[dataitem_name.value == "AlarmCondition"]]></ifExpression>
<thenExpression><![CDATA[CreateAlarm("AlarmCondition", 100, dataitem_name.value + ": Maintenance needed", "dataitem_name")]]></thenExpression>
<!-- do not need to use models if applyToAll is true -->
Extended UI Module
<!-- you can create the module here, but you still have to use the Axeda Console to apply it to the model where the module should show up -->
<step><!-- <step deleteScriptAfter="true"> to delete the custom object after execution -->
<startLabel>Executing Custom Object</startLabel>
<Content>Content of POST request</Content>
<endLabel>Custom Object Executed</endLabel>
<description>Rule Timer Description</description>
<!-- crontab syntax -->
<schedule>0 0/15 * * * ?</schedule>
<!-- The Rule must be of type SystemTimer or AssetTimer -->
<description>Custom App Description</description>
Also included in the starter is a sample HTML application. Note that the Web project’s files are all under artisan-starter-html/src/main/webapp. Also note that apc-metadata.xml contains a section to describe applications such as this one.
Now that you’ve explored a bit, let’s publish the entire app as a Custom Object and an HTML frontend on the Axeda Platform. This app will be immediately accessible via your web browser.
Expand the project folder view and locate the file artisan.properties. This file is used for artisan to upload your project to the Axeda Platform. Edit your username and password (and host if you are not working against dev6.axeda.com). Other properties determine which modules in the apc-metadata.xml are executed on upload. For instance, to upload a custom object, you will need to include the custom object in the apc-metadata.xml and set the doCustomObjects property to true.
Configuring Proxy Settings for Artisan:
# For local Http proxy. Leave commented if you don't use a proxy
#proxyHost = someHost
#proxyPort = somePort
# leave proxy authentication details commented if you don't require authentication
#proxyUsername = someone
#proxyPassword = something
# To enable these modules, set to true. To disable, set to false.
doCustomObjects = true
doCustomApps = true
doRules = true
doModels = true
doRuleTimers = true
doExtendedUIModules = true
Go to a command prompt and cd to your artisan-starter directory. Type:
mvn package –f upload.xml
And sit back while Maven downloads the artisan installer from our Maven repository servers (one time only) and then uploads this project. In the end, you will see a message of this form:
chart example deployed at http://dev6.axeda.com:80/apps/~john_doe_axeda_com/chartexample
Did you find the answer to our featured question:
I've added a custom object to my Artisan project under the Groovy scripts directory. What two steps do I need to take in order to enable the custom object to be uploaded with my project?
Answer: Add the custom object to the apc-metadata.xml and enable doCustomObjects to true in the artisan.properties.
Way to go!