New Component Integration - GeoKnow/GeoKnowGeneratorUI GitHub Wiki

The integration of new components in the generator depends on the interfaces offered by the component:

REST-based APIs. The most straight forward integration consisting of a stand alone component application that provides services. For integrating a REST-based application, it is required to develop a GUI within the Workbench. For instance you can have a look to the Coevolution component.
Web applications. The component provides all its functionality within an application and has it own user interface. Some communication between the component and the integration application has to be defined, and the user experience is compromised because users have to deal with different interfaces. For instance, the integration of FAGI-gis or Sparqlify, provides a initial screen to preconfigure the tool before launching it.
Libraries. If the component is available as a library (e.g. jar), a component interface is required, and in some cases adaptation of communication and data processing is also necessary. An example of this is LIMES, where the creation of a REST-based services was required, in order to use the tool.

In any case, in order to integrate components it is required some front-end development with https://angularjs.org/. AngularJS is a JavaScript framework that provides a MVC architecture. The Workbench has several services, and some directives that can be used by de controllers and the HTML templates.

For adding a new component in the workbench follow next steps:

Describe the component to the configuration file: The components are described using a vocabulary developed within the Linked Data Stack team. The Linked Data Integration Schema, provides the vocabulary to describe the services offered by a component, its version, the required data for using it (i.e. user, password, working directories, etc). And a classification within the Linked Data Lifecycle. Thus, the developer has to add into the system-components.ttl the description of the service of the new component to integrate. Therein, the developer can see the different descriptions of existing components and can use one of those as an example. To describe the service is important to define a type within the Linked Data schema. The available types are described in the schema. As an example, we would like to add a component that do Name Entity Extraction. Then, we add a the following description:
```
 @prefix :        <http://generator.geoknow.eu/resource/> .
 @prefix dcterms: <http://purl.org/dc/terms/> .
 @prefix lds:     <http://stack.linkeddata.org/ldis-schema/> .
 @prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
 @prefix foaf:    <http://xmlns.com/foaf/0.1/> .
 @prefix ontos:   <http://ldiw.ontos.com/ontology/> .

 :NERTool
   a       lds:StackComponent ;
   rdfs:label "My NER tool"^^xsd:string ;
   lds:providesService :NERToolService ;
   foaf:homepage <http://my-ner-tool.example.org> ;
   dcterms:hasVersion "1.0"^^xsd:string .

 :NERToolService
       a       lds:EnrichmentService ;
       rdfs:label "NER Tool" ;
       lds:serviceUrl <http://localhost:8080/ner-tool/api/> .
```
In the same system-components.ttl file, add the Routes to the GUI. To enable the restriction access to the component a Route Restriction, this is used to control the access to the tools.
```
 :NERToolRestriction
  a     ontos:RouteRestriction;
  ontos:route "/workbench/classification-and-enrichment/ner-tool"^^xsd:string;
  ontos:requiresService :NERToolService .
```
If applicable, create a mytool-service.js. If the application to be integrated has a REST interface, creating a service to interact with it may be very convenient. If a service file is created, the service has to be also declared in the angular environment in the src/main/webapp/js/app.js file, and as well added into the src/main/webapp/index.html.
Create the GUIe and Controller. The GUIs for each integrated component are under the /src/main/webapp/js/workbench directory. The developer may add a HTML template and its controller in the directory-category his component fits better. For instance the above described NERTool may go in src/main/webapp/js/workbench/classification-and-enrichment, and a my-tool-controller.js file may be placed there together with the my-tool.html file. The Controller may use the ComponentService in order to extract the information about the component, ant the service created in the step 3 (if any).
Add the route in the angular application. To enable the route in the application, it is required to add a segment in the src/main/webapp/js/app.js file with the URL to the template where the GUI is. You may look into this file and will add a line like:
```
  .when('/workbench/classification-and-enrichment/my-tool', 'workbench.my-tool')
  ...
  .segment('my-tool', {
  templateUrl: 'js/workbench/classification-and-enrichment/my-tool.html' })
  ...
```
Deploy the new configuration files. For the new configuration files to take effect, it is required to setup the Workbench again, but without reseting it. Follow the instructions here, but don't check the reset option.
Activate the component. Once the system is setup again, you will be able to see the component in the settings/components, and the Admin user needs to enable the component so it can be used.