| --- |
| 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 |
