Archive for July 2012
The Argos SDK Part 2
Introduction
Last week I introduced a sample of how to develop mobile apps for Sage 300 ERP using the Argos SDK. In that article I covered where to get the sample and how to get it working. This week, we’ll start to look at how it is put together and how it works.
Sign On
The first thing you need to do is sign-on or authenticate. There is a standard method of authentication built into SData which is explained on the SData website here. Usually you would want to create a sign-on dialog and then feed the results into the SData access layer. This is all done in the sample application.
Basically the file src\Application.js is responsible for orchestrating the running of the application. When it starts running, it calls handleAuthentication() which usually calls navigateToLoginView() to run the login screen. This is done in src\views\login.js. This file displays the UI and gets the data entered. We’ll talk more about how UIs work next. It basically sets up the credentials data structure, calls authenticateuser to save these for the SData layer and then navigates to the initial screen.
Anatomy of a View
For Sage 300 ERP developers this is going to be confusing, because in the Sage 300 ERP world, business logic objects are called Views. But here in the Argos SDK world, Views are UI screens. Basically you provide a data structure (JavaScript object described in JSON notation) with all the fields you want and an HTML template on how you want them displayed, and then Argos has base classes to display these. The Argos SDK uses object oriented JavaScript, so it’s often worth going into the SDK and browsing the base classes to see what things are derived from. This gives you a good idea of what is done for you and what behavior you can override.
The most basic such View is src\views\VendorGroups. This is used as a finder when adding new Vendors. The code is:
define('Mobile/Sage300/Views/VendorGroup/List', [
'dojo/_base/declare',
'dojo/string',
'Sage/Platform/Mobile/List'
], function(
declare,
string,
List
) {
dojo.declare('Mobile.Sage300.Views.VendorGroup.List', [List], {
//Templates
itemTemplate: new Simplate([
'<h3>{%: $.DESCRIPTN %}</h3>',
'<h4>{%: "Code: " + $.GROUPID + " Active: " + $.ACTIVESW %}</h4>'
]),
//Localization
titleText: 'Vendor Groups',
//View Properties
icon: 'content/images/Accounts_24x24.gif',
id: 'vendorgroup_list',
security: 'Entities/VendorGroup/View',
queryOrderBy: 'GROUPID',
querySelect: [
'GROUPID',
'DESCRIPTN',
'ACTIVESW'
],
resourceKind: 'apVendorGroupsFinder',
onRequestDataFailure: function(response, o) {
alert( Mobile.Sage300.Environment.parseErrors(response.responseText) );
Sage.Platform.Mobile.ErrorManager.addError(response, o, this.options,
'failure');
dojo.removeClass(this.domNode, 'list-loading');
},
formatSearchQuery: function(query) {
return dojo.string.substitute('upper(DESCRIPTN) like "%${0}%"',
[this.escapeSearchQuery(query.toUpperCase())]);
}
});
});
This is basically the JSON definition for this View object. This one fairly simple and bare bones, the main points are to define the SData feed in the resourceKind: property, along with the query fields we need. Notice the simplate which is used to format and display each entry in the list, these are described in the next section. Then there is an error handler and a function to perform searches. The rest is done in the base class for this View. For more complicated objects, you will need to override more functions and provide more input (like more details about fields for editing).
Simplate
Simplate is a small templating engine for JavaScript. We use the templates to dynamically combine HTML and data in our views.
The Simplate syntax is a mix of markup, tags and JavaScript code. These are the most common syntax items you’ll see:
- {%= … %}: Output the result of the inner JavaScript
- {: … %}: Output the HTML encoded result of the inner JavaScript
- $: References the data object (in our case, the JSON entry retrieved via Sdata)
- $$: References the data object container (in our case, the view)
You can check out the code and some examples here:
https://github.com/mmorton/simplate
Debugging
When developing you run into lots of bugs, so how to solve them? The nice thing about JavaScript is you just update your files, save them and then hit refresh on the browser to run. But since JavaScript is interpreted and not compiled, you only find out about syntax errors when you run. If the syntax error is bad then it can stop the whole program from running (extra or missing brackets are bad for this), simpler errors will just stop the program when it hits that line of code. Also beware that if you misspell variables, JavaScript will just happily keep going using an undefined value, so be careful.
I like to run in both Firefox and Chrome. Firefox (with Firebug) is good at pointing out syntax errors, so they are easy to fix. Chrome has an excellent JavaScript source code debugger built in that is great for setting breakpoints and tracing through code. Another tool I really like is Fiddler which spies on all the SData server calls being made. From here you can look in depth at what is going on with the SData server.
Since the Argos SDK along with any other libraries it uses are all open source JavaScript projects that means you can examine any of the source code in the Argos SDK and debug into it to see what is happening there as well as what is happening in your own code.
Also remember the SalesLogix and Sage 300 sample applications, chances are you can find an example of what you are trying to do in one of these programs.
Summary
The Argos SDK is a powerful mobile development platform that combines SData with the Dojo JavaScript framework to give quite a deep method to quickly develop mobile applications for various Sage SData enabled products.
The Argos SDK
Introduction
Argos is a framework for creating mobile SData clients using HTML5, JavaScript and CSS. This was originally developed by the Sage SalesLogix group to create the mobile interface for the Sage SalesLogix Mobile product. However since SalesLogix uses SData as its Web Services interface, this library was created entirely on SData. As a consequence it can be used with any product that supports SData.
As part of our Sage 300 ERP 2012 development we tested Argos on our SData feeds and produced a sample mobile application.
Note: that to run this application on your own system, you need at least the Sage 300 ERP 2012 beta.
Argos SDK
The Argos SDK is open source and available on github:
- SDataJavaScriptClientLib: https://github.com/sage/SDataJavaScriptClientLib
- argos-sdk: https://github.com/sage/argos-sdk
- argos-saleslogix: https://github.com/sagesaleslogix/argos-saleslogix
- argos-sample: https://github.com/sagesaleslogix/argos-sample
This includes a JavaScript SData client library that you can use standalone independent of the rest of the SDK along with a sample application that shows Argos running on SalesLogix. The SalesLogix sample application also includes the second sample which shows how to customize the first without requiring code changes to it.
Sage 300 Sample Argos Application
Sorry, the Sage 300 team doesn’t have a github account like SalesLogix right now. However I posted the Sage 300 Sample application and the matching Argos SDK on GDrive here:
- Argo SDK:https://docs.google.com/open?id=0B3d1md_6mdBRc2NtS2c4Mm50N0k
- Sage 300 Sample Application: https://docs.google.com/open?id=0B3d1md_6mdBRZ2hkcEw1bHN6Z0k
Generally you would put these as folders under the c:\inetpub\wwwroot folder. Then you can start the app via: http://localhost/sage300/index-dev.html. (Or substitute your own hostname as needed).
In the Sage300 application there is a runtime folder. This needs to be copied to: C:\Program Files (x86)\Common Files\Sage\Sage 300 ERP\Tomcat\portal\sageERP\runtime. These are the definition files for the SData feeds that this sample uses. After you copy this, you need to restart the “Sage 300 ERP Tomcat” service for them to get read.
CORS
The last gotcha is that the Argos SDK uses Cross Origin Resource Sharing (CORS). This is a mechanism where the server that is serving the HTML can let the browser know its ok to talk to another server. This way the Web Server that serves up the HTML, CSS and JavaScript files can be different than the SData server. Normally this isn’t allowed as it’s considered a severe security threat since it allows malicious programs to send sensitive data to a third server or to send out things like Spam. CORS is an internet standard that provides a way to let the browser know what is ok and what is bad in a secure manner.
As a result, you have to configure the IIS (or whatever web server you use for the static content) to grant access to the SData server. You still have to do this, even if they are the same, since all SData requests from the Argos SDK are CORS validated. The Wiki attached to the Argos SDK on the main Github site above has complete information on this.
But since I’m not exposed to the outside world and don’t usually worry too much about this, I tend to just let CORS say everything is valid with a simple web.config file (in c:\inetpub\wwwroot):
<?xml version=”1.0″ encoding=”UTF-8″?>
<configuration>
<system.webServer>
<handlers accessPolicy=”Read, Execute, Script” />
<httpProtocol>
<customHeaders>
<add name=”Access-Control-Allow-Origin” value=”*” />
</customHeaders>
</httpProtocol>
</system.webServer>
</configuration>
Like I said, don’t just specify “*” like I have for a real situation, but if you are on different networks with a laptop, sometimes this is just easier. Similarly in a real environment, you would want to use https rather than http.
Configuring to Connect to Sage 300 SData Feeds
The key to interfacing to Sage 300 is the development.js file in the configuration folder. To work with Sage 300 it needs to look something like this:
define(‘configuration/development’, [‘Mobile/Sage300/ApplicationModule’], function() {
return {
modules: [
new Mobile.Sage300.ApplicationModule()
],
connections: {
‘crm’: {
isDefault: true,
offline: false,
url: ‘http://localhost/sdata/sageERP/sage300mobiledemo/SAMINC/’,
virtualDirectory: ‘SDataServlet/sdata’,
json: false
}
},
enableUpdateNotification: true
};
});
The key parts are the virtualDirectory to form the correct SData URLs for Sage 300. Remember that Sage 300 URLs start SDataServlet/sdata rather than just sdata. This is to avoid conflict when we are installed on the same server as Sage CRM. So notice the url: tag doesn’t include SDataServlet and then the virtualDirectory tag does. This will then cause the correct URLs to be formed. If you are having trouble with URLs then the Fiddler tool is great for debugging what is going on.
Note that to work, at least you need to change localhost to the server name you are using. Localhost will only work when running on the same computer.
Setup Quick List
So to summarize setup:
- Unzip the two zip files under the c:\inetpub\wwwroot folder.
- Add something to c:\inetpub\wwwroot\web.config for CORS.
- Copy the sage300\runtime folder to …\portal\sageerp\runtime.
- Restart Tomcat
- Edit the development.js file if you need to change the hostname.
Hopefully this will get you going fairly quickly.
Create Your Own App
This blog post is already getting a bit long, so I’ll go into more detail on how this sample program works in a future post. However this should be enough to get you started with the Argos SDK Wiki information and a working sample.
The Argos SDK is written in JavaScript and oriented to JavaScript development, so learning JavaScript is crucial. There are many good books on JavaScript as well as many good free web based resources. I like “Eloquent JavaScript” by Marign Haverbeke since it is fairly short and complete.
The Argos SDK relies heavily on the Dojo JavaScript framework. Along with the Simplate library and iUI library. My experience is that you don’t need to know too much about these to work with Argos, but I imagine if you get deep into it, it doesn’t hurt to know something about these.
Summary
One of the goals of SData is to enable the use of common tools across all Sage products. The Argos SDK is an example of this; it is a mobile SDK library for creating mobile applications that use SData to communicate with on-premise Sage applications. Over time you will see more and more of these sort of tools that leverage SData to provide enhanced functionality for a whole range of Sage applications.
Sage 300 ERP 2012
Introduction
Our Sage 300 ERP 2012 release is now in beta. I thought I’d put together a blog post that summarizes and lists all the other blog posts I’ve written for this release along with a few updates on things that made it into the release since these were written.
When we release Sage 300 ERP, it isn’t just the core ERP modules, it also includes many other Sage integrated products, many of which we are now supporting new versions as well. Plus Sage 300 ERP acts as a platform for many third party modules that extend Sage 300 ERP into many vertical industries.
Summary of Articles on Sage 300 ERP 2012
Here are the various components of Sage 300 ERP 2012 that I’ve blogged on:
Sage Advisor Update
Sage Advisor PEP
Sage 300 ERP 2012 Payment Processing
Sage 300 ERP Inquiry Queries for 2012
Value Added Application Features for Sage 300 ERP 2012
Sage Visual Process Flows
What’s New in the Sage CRM Integration for Sage 300 ERP 2012
SageCRM 7.1 Released
Sage 300 on Windows 8
Sage 300 ERP 2012 Supported Platforms
SData Enhancements for Sage 300 ERP 2012
SData Referenced Resources
All in all quite a large and varied set of new features and services.
Timelines
Roadmap diagrams are always dangerous to put in a blog posting, since once posted, this will be on the Internet for a long time. And as always things are continuously subject to change. At this point the 2012 release is looking good, we were code complete back in June, we are now in beta and our regression testing is going well.
Updates On Previous Blog Posts
Just a few updates since all the previous blog posts.
First we are still adding tweaks here and there to Sage 300. For instance one of the leading causes of tech support calls is from people that tried to activate a new version without backing up their database first. Then activation fails and their database is half converted, now what to do? So tech support asked R&D to change the activation warning screen from just popping up a warning message box, which everyone ignores, to the following:
The hope of this is that it gets more attention and that more people will back up their data before performing activation. Generally we look at the leading reasons for calls to tech support and see if we can alleviate them in the program by making things clearer, easier or better documented.
I blogged on the new functionality in payment processing (credit card processing) earlier in the development process. At that point the team working on it was feature complete on what they had promised for the release. However since then, they have taken the time to incorporate User Centered Design advice into the feature to make it much easier to use. As a result the screens look quite different from my original blog posting. For instance below is the updated screen for capturing batches of pre-authorized payments.
In a similar way the team has made quite a few tweaks throughout the various screens related to credit card processing to either reduce the number of screens, or provide ways to fill them in easier (like providing a way to default addresses), or generally making the labels much clearer. Hopefully all these usability changes will make our Sage Exchange integration a much more enjoyable feature.
By the same token, the Sage Advisor Update screen has gone through several usability revisions and looks much better now. Since this feature is all about update, the first thing that will probably be updated on your system is this component, since it likes to update itself.
For Lanpak usage, we no longer use multiple lanpaks if you login to multiple companies on the same workstation. However we will continue to use multiple lanpaks if you login using multiple Sage 300 users. This should help with the TCO for companies that divide their accounting across multiple Sage 300 company databases.
Quality Debt Reduction
With every release we want to improve the quality of Sage 300 ERP. With this release we have cataloged all known defects at the start of the release and a release certification requirement is that the number of total defects must be lower at release by 15%. So from release to release the number of open defects is reducing. There is also a lot of work going on so we prioritize these defects so that the ones that affect customers the most (based on severity and frequency) will be fixed first. We want to ensure this isn’t a numbers game where we just fix lots of issues about under-lining or field widths in reports. The real aim to ensure we have real measurable metrics that are published in a dashboard that is visible to everyone in Sage up to the CEO, to ensure we are improving quality in a real and measurable way. At this point our quality debt reduction stands at 45%; hopefully, this will improve a bit further by release.
Summary
We have a lot of new functionality in the Sage 300 ERP 2012 release. Please check out the beta, if you are qualified. This release leverages shared components from other Sage groups such as the Visual Process Flow tool from the Sage ERP X3 group, the Sage Advisor Update from Sage UK and Sage Advisor PEP from the Sage 50 US team in Atlanta. There are improvements to the platform with enhanced SData support, paving the way for future development. There are many application features. There is updated platform support and updated support for newer versions of other integrated Sage products.
The Sage 300 ERP development group is very excited about this release, and hope everyone has a great experience with it.
Stephen Smith's Blog 