.. _overview:

EDG App Framework
=================

``EDG-AF`` is a framework for building applications that extend capabilities of `TopBraid EDG <https://www.topquadrant.com/products/topbraid-enterprise-data-governance/>`_. 
Using ``EDG-AF``, auxiliary web services and web applications can be developed with any tools that can build and run a web application.
At build time ``EDG-AF`` generates the necessary glue for the new features to be accessible from the EDG user interface.
``EDG-AF`` also simplifies deployment of applications using configuration specifications.

**How to read this document**

The documentation is organized into the following sections:

* :ref:`Overview <overview>`: this page
* :ref:`architecture`: discusses how ``EDG-AF`` lives in the EDG Ecosystem
* :ref:`tutorials`: provides a walkthrough for developing an ``EDG-AF`` app with Java servlets
* :ref:`how_to_guides`: describes how to run the example ``EDG-AF`` app

  * how to install an EDG app; 
  * how to build the EDG App Framework command line interface (CLI) and libraries; 
  * how to build plugins for deployment in the EDG server
* :ref:`reference`

The following abbreviations are used:

* **EDG**: stands for 'Enterprise Data Governance' and refers to a complete EDG Ecosystem consisting of the EDG server and any EDG Apps
* **EDG-AF**: the EDG App framework

**What is an App Framework?**

Firstly an ``App`` is any software package that adapts EDG for specific business purposes that might need integration with other services.
With an ``App Framework``, tools are provided to build apps that can customize EDG to fit user and business needs. 
Customers can integrate third-party services with the EDG platform.
They can build custom integrations that are a level of complexity or high performance need that makes them unsuitable to realize as customizations of the EDG core product. 
By integrating services using an ``App Framework`` means that you can create an executable ecosystem that’s seamlessly connected and can readily be adapted to execure in different infrastructure configurations.

An ``App Framework`` is a set of software components, along with build and deployment scripts, enabling an application to interoperate with one or more servers.
The framework might be very general and allow a diverse range of app types to be constructed, or, it might provide abstract classes that pre-define whay is expected of different app types.
In the case of ``EDG-AF``, the app types that are supported are importers, exporters and other kinds of software jobs where complex processing may be involved.

Using an ``App Framework`` developers are able to host apps on a single server or multiple servers. 
Configuration files enable build and deployment scripts to do the necessary work to set up a composite of interoperating components.

The typical components that make up an ``App Framework`` can be summarized as:

#. Protocol handlers to establish connections with servers, controlling:
   
   * authentication;
   * API request construction and execution;
   * API response provisioning;
   * exception handling.

#. Monitors for execution surveillance;

#. Framework classes that define the facets of functionality that specific app types need to provide;

#. User Interface components that can be "installed" to the EDG User Interface for invoking an app;

#. Language bindings for one or more programming languages;

#. Declarative configuration scripts that define how the composite set of apps will be built and deployed;

#. Test cases to verify and validate interoperability

The scripts that make up an ``App Framework`` are:

#. Build scripts to create software executables

#. Deployment scripts that, driven by the configuration files, can install, start and stop applications

**What problems does EDG-AF solve?**

To build high-scalable and highly reliable software applications need to be paritioned into composable services that can be built and deployed independently of one another. 
Moving away from a single monolithic, systems are:

#. *Flexible* —  services can be composed and rearranged to quickly deliver new functionality;
#. *Resilient* — an application is no longer a single “monolith” where a degradation in one part of the application causes the whole application to fail;
#. *Scalable* — applications can be realized as services that can be distributed across multiple servers to achieve scalabililty and performance. 

``EDG-AF`` is a way of writing applications that run as part of an EDG Ecosystem.
The applications invoke services that are provided by the EDG server.
These services may be realized with customizations that use Active Data Shapes (``ADS``) or SPARQL Web Pages (``SWP``).

``EDG-AF`` is primarily used for integration with other systems.
``EDG-AF`` apps can be of the following types:

* *Importers*: applications that perform complex transformations of data in diverse formats to RDF for EDG
* *Exporters*: applications that perform complex transformations of data from RDF to diverse formats
* *Jobs*: applications that have demanding performance needs or have to run concurrently in order to synchronize data with external systems

For example, ``EDG-AF`` has been used to export data asset collections as *Data Definition Language*; 
import custom file formats; synchronize relational database tables and Content Management Systems with EDG; 
add new panels to the user interface; and notify an external web service when a workflow commits.

``EDG-AF`` allows developers to:

* use third party tools such as IDEs (Visual Studio Code, IntelliJ, et al.) for their debugging, profiling, dependency management, and other capabilities;
* incorporate third party libraries into their applications;
* develop code in a preferred programming language;
* deploy extensions outside the EDG server for performance or other reasons realting to the complexity of integrating with other systems.

**How does EDG-AF work?**

With ``EDG-AF`` you develop auxiliary web applications and deploy them to your own server or to the EDG Tomcat container. 
EDG-AF apps integrate with the EDG Core Product at pre-defined extension points listed above. 
The applications interact using EDG APIs.

The design of ``EDG-AF`` was inspired by the `Shopify app framework <https://shopify.dev/concepts/apps>`_, 
the `Contentful app framework <https://www.contentful.com/developers/docs/extensibility/app-framework/>`_, 
and the `SharePoint add-in framework <https://docs.microsoft.com/en-us/sharepoint/dev/sp-add-ins/sharepoint-add-ins>`_.

.. toctree::
   :maxdepth: 2
   :hidden:
   :numbered:

   architecture
   tutorials
   how-to-guides
   reference