This blog article will be the first in a series of three, covering the capabilities of the Agama’s AWE SDK and how it can be used to extend the Agama solution with observability and insights into all parts of the platform components and infrastructure.
Abstract
Creating, managing, and delivering video services are complex and challenging tasks, with an ever-increasing pace of innovation. The technology and innovation speed and preferences of operators make most TV and media delivery solutions unique. The TV services are of high importance for the end-users and are sensitive to problems and degradations, so the operators want to have observability into the e2e delivery process, from creation to consumption.
Agama provides a video delivery observability and analytics solution focused on understanding the e2e delivered quality, performance, and usage by tracking the video services’ parameters. Having this kind of capabilities is key for operators but not enough, as there will be other parts of the operators’ unique solutions that are not covered by observability, but are still vital for the delivery of the services.
With the Agama AWE SDK we empower the operators to extend their Agama solution with observability and insights into all parts of their unique platform components and infrastructure. The AWE SDK enables the creation of Agama Enterprise dashboard applications that seamlessly integrate into the Agama environment, allowing the operators to mashup and observe all relevant aspects in a single pane of glass. It also provides a complete development environment that makes it easy to develop, maintain and deploy new functionality without having to touch anything else. Installation is just a drag & drop away.
Introduction
One thing that all modern infrastructure components and solutions provide is REST APIs (Application Programming Interface) that allow both configuration and control, and in some cases also monitoring and supervision. The APIs are a perfect fit for the kind of application support that the Agama SDK provides.
As an example, to highlight the capabilities of the Agama SDK and development environment, we are going to create an Agama dashboard application that can be used as a generic status presentation of any backend system, offering suitable REST APIs that can provide a system health response. This real example will be created from scratch and include both application and presentation logic, as well as per application configuration support.
The Agama dashboard application SDK
An Agama AWE dashboard application is a software package file that can be deployed onto an Agama Enterprise system by drag & drop or by using the Enterprise system CLI. It is a compressed file system using the TAR format and needs to include a manifest YAML file for application properties definitions, an index.html file and a JS function hook serving as the entry point for the application logic. With these criteria in place, the developer can create any type of application using CSS, HTML and JavaScript files.
The easiest way to get started is to use the ADE (AWE Development Environment) which is an application available for Linux, OSX and Windows 10/11. This application makes the development process and building application bundles straightforward and easy.
The ADE is compatible with any browser so one can use Firefox, Chrome, Safari or Edge, depending on preference and operating system. It supports an instant update development model that will reflect the code and data changes immediately, which ensures a fast and iterative development process. It supports CORS (Cross Origin Resource Sharing), which will allow the developer, during initial development and proof of concept, to use external REST APIs that do not yet have a CORS proxy in front, or CORS allowed increasing the development speed.
The ADE application has also several example applications built-in, which can be used at any time to make it even easier to get started.
Application requirements
The goal of this article is to create an application that, besides being a good practical example, can also provide real use for our Agama customers. We concluded that in order to achieve a minimum viable product for this application we should fulfill the following requirements:
- Show relevant backend system status with a clear indicator using REST requests, mapping the HTTP codes to ok/fail with the possibility to specify:
- Name for the test, the time between the tests
- Timeout time
- Active or not
- REST API URI
- HTTP codes for status mapping
With the requirements set we are now ready to start the development.
Project creation
Let’s start by creating a new application project. We do that by starting the ADE application and when the application is up and running, we select the menu option “Create Widget project”.
When creating a new project, you will be requested to point the ADE application to an empty directory of your choice. We chose to name the project “backend-status”. The file system will be automatically populated with a base file structure and necessary files to make it easy to just start coding.
This is the directory and file structure that was automatically created. The file manifest.json contains the application metadata that needs to be filled in in order to have it correctly and uniquely managed by Agama Enterprise. In the CSS/ directory, we find style.css, which we will use later to control the presentation of our application functionality. And in the js/ directory, we find the app.js file, which has the entry point and boilerplate code for initialization of the app in a correct way. We will use this file for the application logic implementation a bit later on. When the project has been created one can just press the button “Open in browser”, which will automatically open the default system browser and start the application.
Nice, everything looks great, and we are now ready to start the real work!
Choosing the application name and id
The manifest file contains several fields and most of them are self-explanatory. The id is particularly important, and it is required that this id be unique across all dashboard applications deployed within a single Enterprise System.
The convention that will ensure the uniqueness even in large systems with many applications is to use a “dot” path structure containing the country, company, type, and application name as the id. In this example, we have filled in the fields according to our company data. The recommendation is that version numbers should be increased by one when the functionality has changed.
The application entry point
We now have the metadata in the manifest in place and can start having a look at the application entry point and boilerplate code.
There are three predefined functions. The first is onAgamaInitialize, which is the core registration method. One rarely needs to modify this function, so we can leave it out for this project.
The onUpdate function is the main application logic method that the Agama Enterprise dashboard infrastructure will call regularly to allow the application to update itself, but will also call at the first creation and if the configuration has changed.
The onConfiguration function is called when the user requests the configuration UI for the application. As application developers we can return the standardized JSON Editor <link here> that exposes configurable parameters, which we will use in the next step.
Configuration
In general, when developing applications, the configuration is often a quite tough thing to get right. Many times in a project it comes in quite late, which results in ad-hoc and hard-to-maintain solutions. This is not the case in the Agama framework, as it provides a complete solution for handling the load, store and validation of the application instance-specific configurations, and the UI to interact with the configuration. This lowers the bar tremendously to get proper and unified configuration support in all applications developed for the Agama solution.
The image below shows the Agama user interface control interacting with the configuration defined by our application.
As mentioned before, the Agama framework provides generalized configuration support based on the JSON editor’s configuration format. This makes it easy and declarative to add all the configuration needed by the application.
In our application requirements we decided to allow for user configuration of several settings, Name of the test, Time between the tests, Timeout value, Active or not, the REST API URI and HTTP codes for status mapping. The image below outlines how the declarative definitions of these settings are made and returned by the onConfiguration function. The resulting configuration UI with this definition is shown in the previous figure. It is possible to not just define simple parameters, with defaults, name, and type, but also control the overall structure in different sections, which is helpful when creating larger and more complex configurations.
Stay tuned for Part 2.
About Anders Svensson
Anders is a successful technology executive with more than 20 years of experience in the telecommunications, information technology, and streaming industry. He is responsible for the technology selections working closely with product management and development teams to ensure the best possible prerequisites in creating Agama’s industry-leading solutions.
