Developing with Axeda Artisan

 

artisan-logoRequirements:  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

This tutorial explains how to develop custom applications on the Axeda Platform with Axeda Artisan, a scaffold that leverages Maven to install Groovy scripts and a zip file of the front end assets (such as the HTML and Javascript files).


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
 

 Artisan Goals

·       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

·       One-command deployment of code to Axeda Platform – no need to log into Axeda Administration UI to deploy and test code.

·       Automatic distribution of Axeda SDK stub classes via Apache Maven – no need to go looking for the latest SDK and documentation.

Highlights

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.

  

  

 First Steps

(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)

Prerequisites

  1. Register an account on developer.axeda.com if you haven't already done so. http://developer.axeda.com/user/register
  2. Download and install the Java 6 Development Kit from http://www.oracle.com/technetwork/java/javase/downloads/jdk6-jsp-136632.html .
  3. *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. 
  4. Install and configure Maven 2.2.1: http://maven.apache.org/download.html , http://maven.apache.org/run-maven/index.html
  5. *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.
  6. Install IntelliJ IDEA 10 community Edition: http://www.jetbrains.com/idea/download/
    or Eclipse: http://www.eclipse.org/
  7. 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.

 Your First Artisan Project

Unzip the artisan-starter.zip to your local development system. You should end up with the following directory structure

artisan-starter/

├── artisan-starter-html

   └── src

       └── main

           ├── assembly

           └── webapp

               ├── images

               ├── scripts

               └── styles

└── artisan-starter-scripts

    └── src

        ├── main

           ├── groovy

           └── resources

        └── test

            ├── 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

 

  

You can verify your change in the Maven Projects section under Axeda Artisan Starter Scripts > Dependencies

 

 

 

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.

 

 Editing Groovy

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.

  

apc-metadata.xml

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"?>
<!--
        apc-metadata.xml
 -->
<apcmetadata version="1.0.0" project="MyCustomApp">

 

Here's how the xml looks for the various objects you can add:

 

Models with data items

    <models>
        <model>
            <name>model_name</name>
            <!--standalone or gateway-->
            <type>standalone</type>
            <DataItems>
                <DataItem>
                    <name>dataitem_name</name>
                    <!--string or digital or analog-->
                    <type>string</type>
                    <visible>true</visible>
                    <stored>true</stored>
                    <!--0 = no history,1 = Stored,2 = no storage,3 = on change-->
                    <storageOption>3</storageOption>
                    <readOnly>false</readOnly>
                </DataItem>
            </DataItems>
        </model>
    </models>

 

Custom Objects with Parameters

    <customobjects>
        <customobject>
            <name>customobject_name</name>
            <type>Action</type>
            <sourcefile>customobject_name.groovy</sourcefile>
            <params>
                <param name="parameter_name" description="(REQUIRED) Str - Parameter Description"/>
            </params>

        </customobject>

   </customobjects>

 

Expression Rules

    <expressionRules>
        <rule>
            <name>expressionrule_name</name>
            <description>Expression Rule Description</description>
            <enabled>true</enabled>
            <applyToAll>false</applyToAll>
            <type>Data</type>
            <ifExpression>
                <![CDATA[dataitem_name.value == "AlarmCondition"]]></ifExpression>
            <thenExpression><![CDATA[CreateAlarm("AlarmCondition", 100, dataitem_name.value + ": Maintenance needed", "dataitem_name")]]></thenExpression>
            <elseExpression/>
            <consecutive>true</consecutive>
            <models>

                <!-- do not need to use models if applyToAll is true -->
                <model>model_name</model>
            </models>
        </rule>
    </expressionRules>

 

Extended UI Module

    <extendedUIModule>

      <!-- 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 -->
      <title>extendedUI_name</title>
      <height>180</height>
      <source>
        <type>CUSTOM_APPLICATION</type>
        <name>customapp_name</name>
      </source>
    </extendedUIModule>   

 

Initialization

<initialization>
        <step><!--  <step deleteScriptAfter="true"> to delete the custom object after execution -->
            <script content-type="xml">customobjectToExecute_name</script>
            <startLabel>Executing Custom Object</startLabel>
            <body>
                <Request>
                    <Content>Content of POST request</Content>
                 </Request>
            </body>
            <endLabel>Custom Object Executed</endLabel>
        </step>
    </initialization>

Rule Timers

    <ruleTimers>
        <ruletimer>
            <name>ruletimer_name</name>
            <description>Rule Timer Description</description>

            <!-- crontab syntax -->
            <schedule>0 0/15 * * * ?</schedule>
            <rules>

                <!-- The Rule must be of type SystemTimer or AssetTimer -->
                <rule>expressionrule_name</rule>
            </rules>
        </ruletimer>
    </ruleTimers>

 

Custom Application

    <applications>
        <application>
            <description>Custom App Description</description>
            <applicationId>customapp_name</applicationId>
            <indexFile>index.html</indexFile>
            <!--<zipFile></zipFile>-->
            <sourcePath>artisan-starter-html/src/main/webapp</sourcePath>
        </application>
    </applications>


HTML app

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.

Upload Project to Axeda

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
doInitialize=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

 

You may browse to this URL and check out what you’ve deployed. It is a simple example that retrieves data from your account via JavaScript/Scripto, and renders a bar chart using the Google Chart API.

 

Custom app re-upload fails against 6.5 because the app upload form changed. The old Artisan doesn’t send the right set of fields. That's why you need the new Artisan. Here's the easy fix: 
  
In your upload.xml, replace the artisan dependency fragment with 
  
        <dependency> 
            <groupId>com.axeda</groupId> 
            <artifactId>axeda-artisan-installer</artifactId> 
            <version>1.0.0-SNAPSHOT</version> 
        </dependency> 
  
Then add this before </project> close tag 
  
    <repositories> 
          <repository> 
            <id>internal</id> 
            <name>Axeda Maven/Ivy Repository</name> 
        </repository> 
    </repositories> 
 
That's it!
Congratulations! You have successfully deployed your first Artisan-based Axeda project. Check back here for more tutorials on Artisan, including deploying Adobe Flex applications. 

 

Be sure to let us know what you think in the forums!

Back to top


 

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!
 

Didn't answer your question or you're looking for more?  Check out other Artisan resources on Axeda Developer and Axeda Mentor Artisan Overview.