Picture of Tom Taylor
Authoring Tool Release v1.0.0-alpha.1
by Tom Taylor - Tuesday, 27 July 2021, 12:11 PM
 

The Adapt team is very pleased to announce the landmark release v1.0.0-alpha.1 of the authoring tool!

v1.0.0 marks the biggest change to the codebase since its initial release in 2015; the culmination of several years at the drawing board redesigning the app architecture from the ground up, laying the foundations for features which simply weren’t possible previously. For this reason, we thought it fitting to give the release an appropriately major version number.

Objectives

After a process of substantial feedback-gathering, we identified the following main areas for improvement:

  • To lower the barrier to entry/reduce the overhead of working with core code for new and existing developers.
  • To facilitate a plug-in based architecture similar to the framework, and therefore reduce the need for major core changes in the future.
  • To improve the stability of core code, and allow more effective automated testing.
  • To expose a consistent and reliable public API for both internal use by the application and to third-party code.

Headline features

From our set of objectives, we created a high-level list of changes:

Modular architecture

The application has been split up into a number of small modules each with well-defined and specific purposes. This allows developers to focus their effort more easily, and reduces the need to have a working knowledge of the whole application.

All of these modules are now managed using npm, which makes it easy to set up installs with custom modules, as well as add/remove/update modules at a later date.

Consistent and conformant API

The API for the authoring tool needed to be updated to be more consistent across the application itself, as well as be more conformant to common web standards and best-practices. This covers everything from naming the conventions we use for the API and data returning from the API, to the use of HTTP status codes and a consistent format for error handling. Abstract classes have been added to help with this, allowing developers to extend from these to inherit common functionality without any extra work.

Better permissions

Defining permissions has been simplified, seeing us switch to a scope-based system which is both easier for the developer and the end user: easier for the developer to restrict behaviour based on meaningful ‘scopes’ rather than by specific URLs and easier to define roles for the end user for the same reason. It also makes roles more flexible, allowing developers to change API endpoints without having a knock-on impact on the roles.

Modernised codebase

In addition to the more stand-out changes, we got to modernise the entire codebase from the ground up, adopting the latest language additions from ECMAScript 6+ (bearing in mind the original codebase was written for ES5).

This includes:

  • A switch to using classes to encapsulate functionality
  • Heavy use of promises and async/await (replacing the older callback approach)
  • Move away from ‘var’ variable declarations in favour of let/const to avoid scope pollution etc.
  • Use of arrow functions to avoid scope-based errors
  • Adoption of native loops and other helper functions

What this results in is much cleaner, more readable code with less reliance on third-party helper libraries such as Underscore.js and Async/Q. The new code should also be much less error-prone code thanks to ES6 features such as the scope improvements (e.g. arrow functions).

Full API documentation

One big area which needed improvement was the developer documentation, which consisted of an ad-hoc collection of documents with no real structure. For this release, we have included full API documentation (made possible via code comments/docblocs). We’ve also written a collection of user guides to accompany the API docs to give more context and worked examples where necessary.

Conformance to JSON schema specification

In line with our endeavours to be more standards-compliant across the board, we have updated all schemas used by the authoring tool to conform to the JSON schema specification (draft 2020-12 at time of writing).

This brings with it many advantages:

  • More familiar to developers
  • Fully documented by the maintainers of the spec
  • Regularly updated, with a view to it becoming a web standard
  • Flexible validation features
  • Good support from many third-party libraries (e.g. validators, form renderers)

Improved app configuration

The aim here was to provide more power to developers to add their own custom configuration to the app, while also making the configuration process simpler for end users (particularly during install). This has been achieved by introducing JSON schemas for configuration data, which not only allows us to check if the config data is valid, but also provide default values where appropriate and integrate with GUIs more easily. The ability to have separate configuration settings for different environments has also been added to allow for more complicated setups.

Continuous integration pipeline

We wanted to make more use of a continuous integration (CI) pipeline to automate repetitive tasks and take some pressure from the development team when it comes to releases. Tasks which we intend to add to the CI process are:

  • Code linting
  • Unit testing
  • Documentation generation

Module list

The restructured app consists of the following separate modules:

  • adapt-authoring-adaptFramework: deals specifically with using the framework to create the Adapt course output, as well as imports and exports.
  • adapt-authoring-api: an abstract module which can be extended by developers in their own modules. Used in many of the core modules.
  • adapt-authoring-assets: deals with asset management.
  • Adapt-authoring-auth: deals with authentication and authorisation of requests to the app API.
  • adapt-authoring-authored: adds metadata to database records to denote when a record was created/updated
  • adapt-authoring-config: deals with the configuration settings for the app
  • adapt-authoring-core: contains the main entry-point for the app as well as abstract classes for extending by other modules.
  • adapt-authoring-courseassets: deals with counting references to assets in courses
  • adapt-authoring-coursetheme: deals with customising the theme applied to a course
  • adapt-authoring-defaultplugins: adds ability to define framework plugins to be enabled by default when a course is created
  • adapt-authoring-installer: an HTML-based installer GUI
  • adapt-authoring-jsonschema: handles JSON schema validation
  • adapt-authoring-lang: handlers the localisation of language strings
  • adapt-authoring-localauth: handles authentication via username/password
  • adapt-authoring-logger: logs messages to the output console
  • adapt-authoring-mailer: handles sending emails
  • adapt-authoring-middleware: adds generic middleware to the Express.js stack
  • adapt-authoring-mongodb: adds support for MongoDB
  • adapt-authoring-mongodblogger: extends the logger module to add log modules to the MongoDB instance
  • adapt-authoring-roles: deals with user roles
  • adapt-authoring-server: adds an HTTP server
  • adapt-authoring-sessions: provides user sessions to remove the need to login each time the web app is visited
  • adapt-authoring-spoortracking: adds support for progress tracking in courses via spoor
  • adapt-authoring-tags: adds ability to tag content with searchable keywords
  • adapt-authoring-ui: the main app UI
  • adapt-authoring-usergroups: adds ability to group users for easier content sharing
  • adapt-authoring-users: deals with users

What next?

The new version of the tool is currently in the first alpha iteration. We need as many people as possible to install this and give it a thorough going over to identify all the bugs that will inevitably be in there and report them as GitHub issues. There are a number that we've already spotted and added to the issues list - please check through these before reporting new ones.

We will fix the issues as quickly as we can. Once we're happy that the code is in a stable state we will declare a public beta which you can, if you're feeling brave, start using with real users.

Once we have a stable release we can return to feature development - of which there's a long backlog that has built up. Hopefully with the new codebase we will see a marked increase in velocity.

Useful links

Picture of Paul Steven
Re: Authoring Tool Release v1.0.0-alpha.1
by Paul Steven - Wednesday, 28 July 2021, 3:46 PM
 

Thank you Adapt team for all the amazing work getting to this stage!

Picture of Jason Wilson
Re: Authoring Tool Release v1.0.0-alpha.1
by Jason Wilson - Thursday, 29 July 2021, 1:56 AM
 

Awesome - looking forward to seeing it in action!

Picture of Chuck Lorenz
Re: Authoring Tool Release v1.0.0-alpha.1
by Chuck Lorenz - Friday, 30 July 2021, 2:55 PM
 

Here's a video overview of the installation: 

With the new installer, I think installation is easier than before. But, you know how it is, when you're not installing the AT everyday, it's easy to forget what config values you need. This video targets us indies--those of us who have installed the AT on standalone computers. Scrub through to see the look of the installer, to review config values, or the few troubleshooting pointers near the end.

But definitely load it up and help us track down some bugs.

Picture of Tom Taylor
Re: Authoring Tool Release v1.0.0-alpha.1
by Tom Taylor - Monday, 2 August 2021, 9:10 AM
 

Thanks Chuck, looking good :)

As a side-note: if anyone has any suggestions for improvements to the installer (including any config option help text), then we're all ears!

Picture of Lars Halkjær
Re: Authoring Tool Release v1.0.0-alpha.1
by Lars Halkjær - Tuesday, 3 August 2021, 10:09 PM
 

Can you install it on an Ubuntu 20 server?

Picture of Steve Cole
Re: Authoring Tool Release v1.0.0-alpha.1
by Steve Cole - Wednesday, 4 August 2021, 8:50 AM
 

Yes, I installed yesterday on Ubuntu 20.

Uploaded images couldn't be moved to a non existent directory:
ENOENT: no such file or directory, copyfile 'temp/formidable/upload_3fa16fe43f843ead8e75a40c0c5d4b10' -> 'data/assets/da/ta/data/assets.png'

Picture of Lars Halkjær
Re: Authoring Tool Release v1.0.0-alpha.1
by Lars Halkjær - Wednesday, 4 August 2021, 9:31 AM
 

When I try to run the install script it stops at the point where the browser should pop up (but this being an Ubuntu server means no default browser). 
Is there a manual way?

Picture of Steve Cole
Re: Authoring Tool Release v1.0.0-alpha.1
by Steve Cole - Wednesday, 4 August 2021, 10:15 AM
 

Type the url (with the port number) into the browser manually.

Picture of Tom Taylor
Re: Authoring Tool Release v1.0.0-alpha.1
by Tom Taylor - Monday, 9 August 2021, 9:43 AM
 

Hi Lars,

Unfortunately there's currently no command-line install option, but this will be added prior to the beta release.

I've logged a ticket for this here, so feel free to comment with any ideas/follow the progress :)

Picture of Lars Halkjær
Re: Authoring Tool Release v1.0.0-alpha.1
by Lars Halkjær - Tuesday, 10 August 2021, 3:30 PM
 

Hi Tom,

I created an ssh tunnel to the server from my desktop which then used my local chrome browser.

Picture of Ailiniyazi Maimaiti
Re: Authoring Tool Release v1.0.0-alpha.1
by Ailiniyazi Maimaiti - Monday, 9 August 2021, 8:49 AM
 

This bug has been fixed, could you try to update the adapt-authoring-assets package?