Oasis Digital, Author at The Oasis Digital Blog

Rapid Prototyping

Here at Oasis Digital we work on many kinds of projects. We start new projects in a “green field”. We revive old projects where former developers are no longer around. We teach classes open to the public, we travel to our customers to teach classes privately. We attack entire projects. We supply brainpower to existing projects.

Among the most fun work: to rapidly create a working-prototype implementation of a new idea.

In projects like this, it is often important to deliver quickly. To make that possible, the right goals and constraints are important. I have listed some of the possible goals and constraints below. Some of these conflict with each other! This is not a checklist of things to always do, but rather a list of ideas to consider.

Reduce the scope of the working-prototype as far as feasible, but no further.
Choose a team small enough to minimize coordination, but maximum parallel productivity.
Choose a programming language and other tools we know best.
Choose a different language and/or toolset, more well-suited to creating maximum functionality with little code for the problem at hand – even if it is not among those where we have the most experience.
Support only the most important browser or two, omitting legacy browser support.
Implement a wide swath of features, but very shallowly.
Choose the most vital/informative parts of the intended software system, and implement those in a working prototype manner, leaving the less interesting parts as static mockups.
Start with a very plain visual appearance, to make it obvious it is “just” a prototype.
Start with a more polished visual appearance, perhaps using an off-the-shelf template, to show the level of polish that will be possible in a more complete project.
Even if the system may eventually be a complex, multi-tier widely distributed system, implement the prototype as client-side only system; no server-side data storage at all. Often enough data can be stored in “HTML 5 local storage” to make it clear whether the project is actually a good idea and should proceed past a mere prototype.
Implement the prototype using something that approximates (but simplifies) the intended long-term architecture, because the prototype may need to demonstrate that it is a suitable architecture.

The final appealing thing about rapid prototype projects: they are straightforward to propose and price, often with a simple statement of work and fixed/firm price.

Preparing for Angular 2.0

Here at Oasis Digital, we have been excited about the possibilities for Angular 2.0 ever since its (somewhat contentious) public debut at the Fall 2014 European Angular conference. That was the conference with the infamous “tombstone” slides, and the frequently misunderstood explanation by the Angular team members that they did not have a migration strategy for Angular 1-to-2 yet. Many commenters at the time seemed to misunderstand the yet part as some assertion that there would be no migration strategy at all. Fortunately, the agitation around that initial announcement has subdued, work has continued, progress is being made.

Though there has been quite a lot of progress on Angular 2, which we have been following (much of the development is being conducted in the open) our recommendation now is that if you don’t have a reason to work with A2 well before its release, you’re probably better off ignoring it a bit longer. As I write this in August 2015, the Angular 2 alpha versions are still rather rough, particularly in the experience of getting started.

But at Oasis Digital we do have a compelling reason to start using new versions before they are ready. We must do this so that we have significant experience when the time comes to start teaching our students (for our Angular class) how to use the new version, and even for the teaching we already include in the class about how to prepare for Angular 2.

One of our primary trainers, Paul Spears, has been leading the charge. Here are links to a couple of repositories he has published, showing a minimal project to get up and running with Angular 2, loaded using JSPM:

https://github.com/dpsthree/NG2-TS-JSPM (TypeScript)
https://github.com/dpsthree/NG2-ES5-JSPM (plain ES5/JavaScript)

There is quite a lot to explain about what is going on in those repositories, here are a few of the most important bits.

We expect that many teams (perhaps most) will concurrently upgrade their development/build tools to the current generation of ES6/2015 module-centric build systems. The leader in the space appears to be JSPM, so we have chosen that for this work. It is also possible (and we will likely publish example this way in the future) to simply load Angular 2 along with its required dependencies using the script tags from downloaded files or from a CDN, of course.

The JSPM configuration may look quite alien compared to the familiarities of Grunt or Gulp. This is because of the above-mentioned module loader approach, and because JSPM already understands many things that must be explained to Grunt or Gulp by the user or a plugin.

These examples are set up for development, loading numerous separate tiny libraries using numerous HTTP requests; but JSPM and similar tools also have an excellent solution for production asset preparation, using essentially the same configuration information to package all of the JavaScript into a file or two.

These repositories show working examples as of right now, early August 2015. Angular 2 has been changing quite substantially from one alpha to the next. Moving up to the next version will likely require adjustments, as it has in previous versions. This is definitely alpha software.

The config.js file looks quite scary, but much of the contents there are generated by JSPM tooling. With some adjustment, it is possible to omit the hairiest block of information therein from source control, and instead treat it as a build artifact. As you look at the contents of that file, remember that you will not have to write the bulk of it.

Summer 2015 Intern Hackathon

Oasis Digital summer intern program starts with 3-4 weeks in which the interns primarily learn (at a firehose pace) as much as possible about the technologies we have selected – Angular, JavaScript, HTML, etc. The rest of the summer, the interns work on projects to create software.

In between, we hold an internal, one-day hackathon. The theme this year was “Minions”, and the goal to build a working game based on this theme. As you can see in the video below, the interns did a surprisingly good job, given just a few weeks of Angular knowledge and less than eight hours of work time.

Angular 2.0 Discussion – Angular lunch

At Oasis Digital we host a St. Louis Angular Lunch each month. Many months an outside speaker comes in (especially if anyone volunteers!), other months someone from Oasis Digital speaks. In July 2015 we did something a bit unusual, several of us sat around and just talked about our Angular 2.0 preparations for a while. Although quite informal, it was well received. See the video embedded here.

Preparation for Angular 2.0 can include a lot of things, here are a few of the most important which came up in the discussion:

Now is the time to learn/use TypeScript. (We have converted a large Angular project to TypeScript.)
Now is the time to learn/use ES6/2015. (We have converted a large set of Protractor tests to ES2015.)
Angular 2.0 uses native ES6/2015 modules – which already work today.
The new “component router” for Angular 2 is also intended to arrive as a backcourt in Angular 1.x; it is very different from both the old Angular router and the very popular angular-ui-router. Although much work remains to be done, it is possible to start learning it now.

One topic of lively discussion was guessing when Angular 2.0 might ship. No ship date has been released, but several of us in this discussion thought it could be problematic for the Angular community if another major US spring conference goes by without A2. Therefore one obvious guess: Angular 2.0 will ship, perhaps just as “beta”, approximately around the next spring Angular conference. No one present has any connection to the Angular team, so this is just an outside, educated guess.

Transcript

We have also transcribed the discussion to text, provided below. This is a rough, first-draft transcription, so any errors are probably from that process.

Continue reading Angular 2.0 Discussion – Angular lunch

Automated User Acceptance Testing – Matt Follett – Angular Lunch

This month (May 2015) at the Angular Lunch we had a very special guest speaker. Matt Follett (currently working at Observable Networks) shared his extensive experience working with end-to-end testing of browser-based web applications, including Angular applications. Although Matt only briefly mentioned Protractor (the Angular specific wrapper around Selenium), nonetheless almost everything he said was highly relevant to protractor.

Matt did not pull any punches in describing the difficulties of this type of test, and his comments certainly match our experiences at Oasis Digital testing Angular applications using Protractor. Still, the payoff of this level of testing is so high that we find it generally worth the effort. Automated testing is a (the?) way to keep quality up and regressions away as an Angular application grows in complexity and size.

Perhaps the best part of Matt’s talk is toward the end, when he (gently) compares the various available hosted browser/selenium services.

Transcript

We have also transcribed the the talk to text, provided below. This is a rough, first-draft transcription, so any errors are probably in that process, rather than in Matt’s actual content!

Continue reading Automated User Acceptance Testing – Matt Follett – Angular Lunch

ng-conf Review Roundtable – Angular Lunch

Several members of the Oasis Digital team attended ng-conf in Salt Lake City recently. This month for the St. Louis Angular Lunch (April), we had a roundtable discussion of the conference and what we all learned at it. Here’s a video of the discussion:

Transcript

Here is the discussion, transcribed to text. This is a lightly edited, draft transcription, so any errors are probably from that process.

Continue reading ng-conf Review Roundtable – Angular Lunch

Mantis to JIRA Translator / Importer

A few years ago we needed to migrate a large project issue tracker from Mantis to JIRA. At time, JIRA’s Mantis import feature was very limited; looking at it now in 2015, it appears to be more mature.

We needed specific features for the Mantis to JIRA conversion:

Include comments
Include attachments
Include inter-issue links

To achieve this, we implemented our own Mantis to JIRA import. It takes the form of a Java program, which interacts with Mantis and JIRA as follows:

Uses the Mantis SOAP API to retrieve issues data, comments, links, and attachment metadata.
Uses the JIRA CSV import for the above.
Enables JIRA to retrieve attachments from Mantis over HTTP during CSV import.
Uses the JIRA REST API to put in issue links – they are (were?) not supported via the JIRA CSV import.
Translate usernames via a lookup file, as JIRA usernames may not match Mantis username.

The resulting software was tuned for our specific needs, but it also reasonably generic: none of the URLs, names, or authentication settings are baked in, they are all set via configuration. Therefore, we are happy to release the software here, in case anyone finds it useful. All necessary files (aside from Mantis, JIRA, and a JVM) are included in the ZIP file, including rough documentation.

OD-Mantis-JIRA.zip

This is a binary-only release; we haven’t cleaned up the source code for release, or decided whether to do so. This software at no cost but with no promise of support; but feel free to contact us with questions, or to engage us in consulting work using this tool.

Controller As, and dividing controllers for modularity – Angular lunch

This month at the St. Louis Angular Lunch (which we host), John Baur explained the “controller as” syntax, which has come to be the preferred and recommended approach. Afterward, he showed examples of dividing a long, complex controller into shorter, more modular controller-components. Here is a video – we are experimenting with the best way to record these lunch talks, hopefully the code is readable enough. We’ll do something better as we learn how.

Transcript

We have also transcribed the the talk to text, provided below. This is a rough, first-draft transcription, so any errors are probably in that proces./strong>

Continue reading Controller As, and dividing controllers for modularity – Angular lunch

Task Based User Interfaces

Here at Oasis Digital, the bulk of our work is on complex business data systems. These projects sometimes involve a so-called task-based user interface. Briefly, this is an interface where the operations available to the user are presented in terms of the problem domain, rather than in terms of editing data. Other names for this idea include “task-focused user interface” and “inductive user interface”.

Origins

I was unable to determine the specific research/practice origins of task-based UI, but it is most commonly seen as arriving from three main directions. First, the inductive user interface guidelines published by Microsoft around 2001 lay out a detailed description and motivation. Second, the domain driven design (DDD) and command query responsibility separation (CQRS) communities often described task-based UI as suitable for use in front of the system built with those principles. Third, simply looking at mass-market software there are numerous examples.

CRUD

Task-based UI is the opposite of CRUD UI, a convenient foil. Many software systems have numerous features which are readily described as CRUD: create, read, update, delete. Some developers describe their work as primarily creating CRUD systems, with either pride or disdain. When analyzing a proposed feature or proposed software project, we sometimes evaluate the extent to which the project is “just CRUD” versus behavioral functionality. Brought to the user interface, CRUD typically means screen after screen in which users can make an entity of some kind, find an existing one, update one, or remove one. In other words, a minimal veneer over basic database operations.

Simple CRUD user interfaces have the advantage that they are generally easy to create, and amenable to common tooling. Many development environments offer wizards or libraries to ease such creation, and this dates back to at least early 1990s, and probably much farther than that.

Therefore, CRUD has a lot of appeal when first creating a new application. Unfortunately, a system built primarily around CRUD tends to make behavior beyond minor validation unduly difficult to implement. If you find yourself squeezing business logic into an “on change” or “on click” event handler somewhere, you are probably experiencing this difficulty. As systems grow in complexity this bad fit can consume vast amounts of time and money.

There is a way out, and that is a task-based user interface, one which presents the user with options and actions which fit the problem domain of the software, rather than those which appear to manipulate data in trivial ways.

Change of Address Example

A common example to explain task-based UI is a change of address operation in a system which has subscribers, members, or some other class of people to whom things might be mailed etc. The CRUD approach to change of address is simple: the user searches for the appropriate user record, views that record, moves the cursor to the address fields, types over those values, and clicks “save”. Very convenient, very easy to program.

Unfortunately, down the line if there is nontrivial behavior in the system, it can be extremely difficult to determine what such an edit means. Was the address corrected because it had been mis-entered in the past? Was the ZIP Code changed because the post office changed the ZIP code assigned to that physical location? Or does this edit represent the person moving to a different place of residence? If the latter, how might that affect them in terms of the problem domain?

To avoid this, a task-based user interface would not only present address fields which can be edited. Rather, the user would see information about a person (including their address) then have options (buttons or whatever else is suitable in the visual UI guidelines at hand) with names like “correct mis-entered address”, “subscriber moved to another residence”, etc. Such explicit actions make it possible to capture the underlying domain-level meaning, rather than just edits to data fields. A downstream system receiving this information could then respond appropriately.

Choose Your Words Wisely

Task-based user interface is therefore to a considerable extent about words: the words which describe actions the user can take. If a system merely uses a task-based user interface on top of a CRUD-centric back-end implementation, then the words can at least be chosen well in the user interface. If the system uses a domain driven approach internally, then some of the well-chosen words in the user interface may become part of the ubiquitous language used throughout the implementation.

I encourage developers to consider a task-based approach even if the underlying system is not particularly domain driven.

Add, Edit, Delete, +, –

Speaking of words, having built numerous user interfaces, I very often still “default” to wire framing with button labels like “add” and “delete”. Such things are fine for an early initial wireframe, but task-based design principles suggest reconsidering whether a more specific set of operations is suitable.

An example came up at work today with a list of employees, and the initial proposal was a “delete” button next to each one. But one does not merely delete an employee: at even the most heartless of companies there will be quite a lot more process involved in removing an employee from a list of employees. A system which manages the employees then, should probably have some sort of process flow around that removal, and it should use words other than “delete”.

A Final Quip

If the user wanted Excel, they would use Excel. If they are using an application which is instead specific to a problem domain, then it should have features, both internally and at the user interface level, relevant to that problem domain.

Links

http://en.wikipedia.org/wiki/Task-focused_interface
http://msdn.microsoft.com/en-us/library/ms997506.aspx
http://codebetter.com/iancooper/2011/07/15/why-crud-might-be-what-they-want-but-may-not-be-what-they-need/
https://cqrs.wordpress.com/documents/task-based-ui/
http://stackoverflow.com/questions/12255874/what-is-an-example-of-a-task-based-ui
http://codebetter.com/gregyoung/2010/02/16/cqrs-task-based-uis-event-sourcing-agh/

ES6 for AngularJS – Angular Lunch

A few months ago, Oasis Digital started a monthly St. Louis Angular Lunch. At the November 2014 lunch, we had a guest speaker: Mark Volkmann of OCI. Mark talked about ES6 and the Traceur compiler, and briefly how they fit in to developing Angular applications today.

Transcript

We have transcribed the talk about to text, provided below. This is a rough, first-draft transcription, so any errors are probably from that process.

Continue reading ES6 for AngularJS – Angular Lunch

Jira Jumble, a Test Data Generator for Jira

Update: Jira Jumble, and a wide range of Jira-related training and services, are now available through our sister company Expium.

At Oasis Digital, we teach a Jira class in which students learn hands-on how to build workflows, administer Jira, and overcome common challenges. While writing the course material, we realized that it is difficult to fully understand the features unless you have a significant amount of data in Jira: issues, projects, users, with important dates in a range of dates near the date of the class.

One obvious way to obtain this is to use or copy a real (“production”) Jira instance, but students are wisely hesitant, as are we, to bring up a copy of a production Jira instance (full of proprietary information) to use in class. Instead, we need to be able to generate a populated Jira instance with random but useful data. In the past there have been tools for this from Atlassian or other makers, but we found none of those tools are available for the current (as of 2014) Jira versions; and they had been packaged as Jira plug-ins for Jira Server, which means they cannot be installed into Jira Cloud (formerly called Jira OnDemand).

We solved this problem by creating Jira Jumble, a random data generator tool for Jira. We then realized that it would probably be helpful to many other people using or learning Jira so we made it available online. We expect to add additional features and enhancements over time based on the class needs and the feedback we receive.

Please give it a try, we are eager to hear what people think of it.

As a reminder, this test data generator is intended to be used to populate a new, empty, throw away Jira instance for testing and learning. It works with both Jira Server and Jira Cloud. Do not import its data to your production Jira Server or Jira Cloud instance!

(photo credit)

Data Services for AngularJS Applications

I wrote recently about data/API services for complex “single page” JavaScript-heavy web applications. Everything there applies to AngularJS as well as other frameworks (Ember, Knockout, React, etc.), but there are some particulars to keep in mind for ease of interaction between an AngularJS web application and a data service. This topic is also asked about in almost every “Angular Boot Camp” class I teach, so by posting this I have an online resource to point at.

Use RESTful URLs and HTTP Methods

By following RESTful patterns rather than inventing ad-hoc patterns for a server API shape, your code will fit in more easily with the rest of the software industry. This reduces the friction in bringing on more developers, in integrating your application with others, and so on. A RESTful server API will operate easily with AngularJS’s built-in mechanisms for working with a server, whether you use plain $http, $resource, or Restangular. For example, all of those already assume that the HTTP status codes indicate success and failure, so do not make up your own way of encoding failure within HTTP “200” success.

Avoid dogma in REST design, though. Most of the time, you can make a server API shape reasonably RESTful with approximately the same implementation effort as something ad hoc. If you have a case where a RESTful design will require substantially more work than something else, consider an “escape hatch”: a portion of your API that isn’t particularly RESTful, hidden behind a generic POSTable endpoint.

Make Data Binding Easy

I assume that by choosing AngularJS, developers aim to leverage its strengths rather than fight it. That means embracing “HTML enhanced”, data binding, and other banner AngularJS features, rather than manually manipulating the DOM (which immediately fails code review here), mostly passing information around using bindings and $watch rather than events, etc.

Therefore, if possible make your data service return data in a shape already suitable for binding in your AngularJS application. Done well, this can reduce the amount of JavaScript code you must write to populate a complex screen to almost nothing. By complex, I mean a screen which contains the modern equivalent of numerous master detail relationships, hundreds of fields, etc.

Of course, JavaScript is a powerful and convenient language for data structure manipulation, so in a sense it does not matter what shape of data is returned from a server; it is always possible to process that data into a shape suitable for data binding. Hence this guideline is oriented toward ease and speed of development when the server code is being written fresh.

(As an aside, I am not 100% sold on data binding; there are other approaches, like that taken by React, which have significant advantages. But if you are using AngularJS, embrace its strengths. Use data binding pervasively.)

Make Commands / Saves Easy Also

Following along from the above, a conveniently and idiomatically crafted AngularJS application will typically yield JavaScript data structures suitable for PUT or POSTing back to a data backend. Make your server accept PUT or POST of updated or new data in the same object “shape” as it returned data. This way, the data can make a round-trip from the server, through data bindings, to be manipulated by a user, then back to the server; all with very little code to write.

This applies to commands (in the CQRS sense) also. If a user is working with the screen via data binding, then that data binding can often yield a data structure ready to send to a server with a couple of lines of code. If you find it necessary to write extensive lines of code to formulate a server interaction, perhaps either your data binding or server should be adjusted stat.

Consider NodeJS on the Server Side, for Code Sharing

Working with complex client-side web development, you will almost certainly use NodeJS in your development toolchain, even if you are not using NodeJS for your data services.

But NodeJS is worthy of consideration for this key reason: it enables code sharing between the front end and back end. With some care in crafting modules, chunks of functionality which must be implemented on both sides of the client/server API (such as validation, but also many kinds of domain logic) can be reused across both, ensuring consistent implementation and eliminating duplication.

There are numerous other platforms worthy of consideration for other reasons. Stay tuned here (and follow me on twitter), I will have more to write about that.

Guard Your Innovation Budget

If your organization is in the process of adopting AngularJS for the first time, consider not simultaneously adopting a new server-side technology. As humans we each have a certain ability to absorb change, and doubly so for organizations comprised of many humans working together. You will probably get better results if you switch to a new client-side development toolkit in a different year then you switch to a new server side development toolkit. I think of this as having an “innovation budget” which can either be concentrated on one layer at a time, or diluted across more than one layer.

Help Wanted

If anyone knows of convenient source code examples already online of doing these things well versus poorly, please contact me – I would love to add links. Given sufficient time I may create the examples, but with the pace of change in our industry these tools could be obsolete before that happens!