Merge "[master] AppAgent fix - linking WebApplications without service"
diff --git a/doc/EPTF_Service Framework_CNL113865_DS.adoc b/doc/EPTF_Service Framework_CNL113865_DS.adoc
new file mode 100644
index 0000000..78e243b
--- /dev/null
+++ b/doc/EPTF_Service Framework_CNL113865_DS.adoc
@@ -0,0 +1,158 @@
+---
+Author: Tamás Levente Kiss
+Version: 1551-CNL 113 865, Rev. PA1
+Date: 2018-01-16
+
+---
+= EPTF Service Framework, Description
+:author: Tamás Levente Kiss
+:revnumber: 1551-CNL 113 865, Rev. PA1
+:revdate: 2018-01-16
+:toc:
+
+== System Requirements
+
+EPTF Service Framework is written in python and can run on any device supporting python.
+
+= Functionality
+
+== General
+
+EPTF Service Framework (ESF) can be used to build different applications by implementing and selecting the appropriate microservices to fulfill the application’s requirements. ESF itself also provides built-in microservices which are the following:
+
+* DataSource
+* Authenticator
+* Playlist
+
+The framework comes with a set of tools to help microservices serve basic or `DsRestAPI` HTTP requests.
+
+For more information on `DsRestAPI` see https://erilink.ericsson.se/eridoc/erl/objectId/09004cff8b30d663?docno=39/15516-CNL113512Uen&action=current&format=msw8[DsRestAPI Function Description]
+
+Microservices implementing `DsRestAPI` may also implement user interfaces with the help of EPTF Web GUI (EWG). If so, the application needs to implement a GUI configuration handler microservice to provide the EWG a GUI configuration descriptor. This microservice should implement a `createConfig()` function, returning a valid EWG configuration descriptor in JSON format. The function has access to the user groups of the user accessing a web application, therefore it could decide whether the user specific user has access to the web application or not.
+
+The descriptor should also contain EWG specific customization descriptors and HTTP resource directory information.
+
+For more information on the structure of the EPF Web GUI descriptors and on how to write a web application based on EWG, see the https://erilink.ericsson.se/eridoc/erl/objectId/09004cff8cd8deec?docno=1551-CNL113864Uen&action=current&format=msw8[EPTF Web GUI] documentation.
+
+Overview of the ESF:
+
+ESF’s central component is the `AppAgent` module, which loads the microservices located in directory, and also serves as an HTTP server to serve microservice’s API, and the possible web application resources (html, js and other files).
+
+The microservices should provide an API extension (a string value), which is unique in the application’s context, and has the role of an address for a specific microservice in the application. The microservices may implement HTTP handlers (a function named `handleMessage`), where HTTP requests will be forwarded. If the function is implemented, `AppAgent` will forward the requests with the appropriate extension to the addressed microservice.
+
+image:images/Overview.PNG[alt]
+
+All the microservices are running on the same python context, therefore the application’s performance is limited. If one of the microservices is performance-critical, it is advised to handle its critical tasks in separate threads (separate real system threads –not python threads; or separate python contexts). It is not advised to block a request handler in any circumstances, because it will affect the whole application’s performance.
+
+[[esf-s-built-in-microservices]]
+== ESF’s Built-In Microservices
+
+=== DataSource
+
+Serves a `DsRestAPI`. The API can return the source names registered as data sources, and the following basic operators (also as data source elements):
+
+* not
+* ==
+* !=
+* >
+* >=
+* <
+* <=
+* and
+* or
+* match
+* not match
+* sum
+* exists
+* forAll
+* dataElementPresent
+* sizeOf
+
+=== Authenticator
+
+Handles user groups and users. A user can be part of multiple user groups. If authenticated, the user and group information of a request is forwarded to the microservice’s handler functions, and the microservice can decide whether to serve the request as an authenticated request or not.
+
+=== Playlist
+
+Can issue scheduled, potentially conditional requests to any microservice which serves a `DSRestAPI` compatible interface. The scheduled commands and their relations are described by a JSON file matching the Playlist’s schema.
+
+This microservice comes with a user interface part, in order to let the user edit the JSON descriptors graphically.
+
+= Usage
+
+== Writing an Application Over ESF
+
+An application built with the help of ESF should implement microservices with functionalities specific to the application needs. The microservice interface has 3 functions out of which one is optional:
+
+=== Function `getDataSourceHandlers` (optional)
+
+Has no parameters. Should return the DsRestAPI specific handler function references: the getDataHandler and setDataHandler function references.
+
+=== Function `close` (mandatory)
+
+Has no parameters nor a return value. It is going to be called before AppAgent closes.
+
+=== Function `handleMessage` (mandatory)
+
+The function has the following function parameters:
+
+* method – HTTP method
+* path – HTTP full URI
+* headers – HTTP headers list
+* body – HTTP body
+* userCredentials – user name and group information
+* response – HTTP response object. In case of DsRestAPI responses, the object’s `body` field needs to be filled with the JSON response string, and the `headers` field’s `content-type` field needs to be set to "application/json" accordingly.
+
+== Deployment and Configuration
+
+There are 2 ways to run an application built up on the ESF.
+
+1. Copying Needed Files to the Destination
++
+The first way is to copy the framework’s files and the needed set of microservices on the destination location. The server port and address can be configured in a _config.json_ file located in the working directory.
++
+In this case, the application can be started by running the ESF’s _AppAgent.py_, with the needed subset of microservices deployed in the Microservices directory in the ESF’s directory hierarchy.
+
+2. Creating an Executor Script
++
+Alternatively, all the microservices can be kept in the Microservices directory, and different subsets of microservices with different configurations can be run from a python script created for this purpose.
++
+In this case, the `runAppAgent` public function located in the `AppAgent` module can be called directly from a python script. The server configuration and the microservices to be loaded had to be defined as function parameters during this function call.
+
+== Compiling and Running
+
+All modules are using python with `ldap` add-on. The application was tested with python version 2.7.13, and 2.7.9-addons-ldap. Should also work with the latest 2.7 versions.
+
+= Functional Specification
+
+== Structure of the Source Code
+
+The source code is organized into the following directory structure:
+
+image:images/Source_code_structure.png[alt]
+
+= Abbreviations
+
+ESF:: EPTF Service Framework
+
+API:: Application Programming Interface
+
+GUI:: Graphical User Iterface
+
+EWG:: EPTF Web GUI
+
+JSON:: JavaScript Object Notation
+
+= References
+
+[[_1]]
+[1] EPTF Web GUI +
+https://login.microsoftonline.com/92e84ceb-fbfd-47ab-be52-080c6b87953f/saml2
+
+[[_2]]
+[2] DsRestAPI function description +
+https://erilink.ericsson.se/eridoc/erl/objectId/09004cff8b30d663?docno=39/15516-CNL113512Uen&action=current&format=msw8
+
+[[_3]]
+[3] UDsRestAPI user guide +
+https://erilink.ericsson.se/eridoc/erl/objectId/09004cff8b30d64a?docno=39/19817-CNL113512Uen&action=current&format=msw8
diff --git a/doc/EPTF_Service Framework_CNL113865_DS.pdf b/doc/EPTF_Service Framework_CNL113865_DS.pdf
new file mode 100644
index 0000000..a5fd579
--- /dev/null
+++ b/doc/EPTF_Service Framework_CNL113865_DS.pdf
Binary files differ
diff --git a/doc/change.log b/doc/change.log
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/change.log
diff --git a/doc/images/Overview.PNG b/doc/images/Overview.PNG
new file mode 100644
index 0000000..d366a54
--- /dev/null
+++ b/doc/images/Overview.PNG
Binary files differ
diff --git a/doc/images/Source_code_structure.png b/doc/images/Source_code_structure.png
new file mode 100644
index 0000000..9b46eff
--- /dev/null
+++ b/doc/images/Source_code_structure.png
Binary files differ