A neW concept of pubLic administration based on citizen co-created mobile urban services Grant Agreement: 645845 D2.9 – REPORT ON THE WELIVE OPEN SERVICE LAYER V1
DOC. REFERENCE: WeLive-WP2-D29-REP-160419-v10 RESPONSIBLE: FBK AUTHOR(S): ENG, TECNALIA, UDEUSTO, FBK, CNS, INF, DNET DATE OF ISSUE: 19/04/16 STATUS: FINAL DISSEMINATION LEVEL: CONFIDENTIAL
VERSION DATE DESCRIPTION v0.1 06/11/2015 Definition of the Table of Contents and distribution of tasks 17/01/2016 Description of specifications of the Visual Composer, query mapper and v0.3 controller v0.7 21/01/2016 Description of Social Wrapper and Web Scraper v0.8 27/01/2016 Description of specification of WeLive Player Description of Logging BB 16/03/2016 Description of specification of AAC, WeLive player test, ethical issues and v0.9 version ready to be externally reviewed v0.10 31/03/2016 Reviewers´ comments processed v1.0 19/04/2016 Visual Composer tests completed and final version ready for submission
D2.9 – Report on the WeLive Open Service Layer v1 page 1
INDEX 1. EXECUTIVE SUMMARY ...... 8 2. INTRODUCTION ...... 9 3. OVERVIEW OF WELIVE OPEN SERVICE LAYER AND HIGH LEVEL ARCHITECTURE ...... 10 3.1. REQUIREMENTS ...... 10 3.2. ARCHITECTURE ...... 11 3.3. DEPLOYMENT ...... 13 4. OPEN SERVICE LAYER SPECIFICATIONS ...... 14
4.1. BB METAMODEL ...... 14 4.2. CORE PROFILE ...... 15 4.2.1. BUILDING BLOCKS ...... 15 4.2.1.1. Artifact class ...... 15 4.2.1.2. Building Block class ...... 16 4.2.1.3. Dataset class ...... 17 4.2.1.4. PublicServiceApplication class ...... 17 4.2.2. BUILDING BLOCK ENTITIES ...... 17 4.2.3. LEGAL CONDITIONS ...... 18 4.2.4. INTERACTION PROFILE ...... 18 4.2.4.1. Interaction Point class ...... 19 4.2.4.2. TechnicalConstraint class ...... 20 4.3. SECURITY PROFILE ...... 20 4.3.1. COMMUNICATION MEASURES ...... 21 4.3.1.1. ProtocolConstraint class ...... 21 4.3.1.2. OriginConstraint class ...... 22 4.3.2. AUTHENTICATION MEASURES ...... 22 4.3.2.1. IdentityProvider class ...... 23 4.3.3. AUTHORIZATION MEASURES ...... 23 4.3.3.1. Permission class ...... 24 5. CONTROLLER SPECIFICATIONS ...... 25
5.1. REST API ...... 25 5.2. CONTROLLER UI ...... 28 5.2.1. FUNCTIONAL ASPECTS OF THE CONTROLLER ...... 28 5.2.2. DETAILED REQUIREMENTS AND USE CASE MODEL ...... 30 5.2.2.1. DETAILED REQUIREMENTS ...... 30 5.2.2.2. USE CASE MODELS ...... 42 5.2.3. DYNAMIC MODEL AND INTEROPERABILITY DEMANDS ...... 44 5.2.3.1. FLOW CHART ...... 44 5.2.3.2. INTEROPERABILITY WITH OTHER WELIVE COMPONENTS ...... 45 5.2.4. TECHNOLOGY CHOICE REASONING AND USAGE DESCRIPTION FOR IMPLEMENTATION ...... 47 5.2.5. ARCHITECTURE AND DEPLOYMENT DIAGRAM OF THE CONTROLLER ...... 48 5.2.6. DOCUMENTATION AND USER MANUAL ...... 49 5.2.6.1. Access ...... 49 5.2.6.2. Language selection ...... 49 5.2.6.3. City selection ...... 49 5.2.6.4. Registering ...... 50 5.2.6.5. Log in ...... 50 5.2.6.6. WeLive tool selection ...... 51 5.2.6.7. Log out ...... 52 5.2.6.8. WeLive support ...... 52
D2.9 – Report on the WeLive Open Service Layer v1 page 2
5.2.7. DATA PROTECTION RELATED REQUIREMENTS ...... 52 5.2.8. FUNCTIONAL TESTS RESULTS OF THE CONTROLLER ...... 56 6. VISUAL COMPOSER SPECIFICATIONS ...... 57
6.1. FUNCTIONAL ASPECTS OF THE VISUAL COMPOSER ...... 57 6.2. DETAILED REQUIREMENTS AND USE CASE MODEL ...... 58 6.2.1. DETAILED REQUIREMENTS...... 58 6.2.2. ACTORS AND USE CASES ...... 71 6.2.3. Use Case Models ...... 73 6.3. DYNAMIC MODEL AND INTEROPERABILITY DEMANDS ...... 91 6.3.1. SEQUENCE DIAGRAMS ...... 91 6.3.2. INTEROPERABILITY WITH OTHER WELIVE COMPONENTS...... 112 6.4. TECHNOLOGY CHOICE REASONING AND USAGE DESCRIPTION FOR IMPLEMENTATION ...... 116 6.5. ARCHITECTURE AND DEPLOYMENT DIAGRAM ...... 117 6.6. DOCUMENTATION AND USER MANUAL ...... 118 6.6.1. Import Data or Services ...... 118 6.6.2. Create a mashup project...... 119 6.6.3. Create a mockup project ...... 128 6.7. DATA PROTECTION RELATED REQUIREMENTS FOR VC...... 136 6.8. FUNCTIONAL TESTS RESULTS OF THE VISUAL COMPOSER ...... 139 7. WELIVE PLAYER SPECIFICATIONS ...... 143
7.1. FUNCTIONAL ASPECTS OF THE WELIVE PLAYER ...... 143 7.2. DETAILED REQUIREMENTS AND USE CASE MODEL ...... 143 7.2.1. DETAILED REQUIREMENTS...... 143 7.2.2. USE CASE MODELS...... 148 7.3. DYNAMIC MODEL AND INTEROPERABILITY DEMANDS ...... 150 7.4. TECHNOLOGY CHOICE REASONING AND USAGE DESCRIPTION FOR IMPLEMENTATION ...... 152 7.4.1. WLP Mobile App ...... 152 7.4.2. WLP Server ...... 152 7.5. DOCUMENTATION AND USER MANUAL ...... 153 7.5.1. Installation ...... 153 7.5.2. Mobile app user guide ...... 153 7.6. DATA PROTECTION RELATED REQUIREMENTS ...... 156 7.7. FUNCTIONAL TESTS RESULTS OF THE WELIVE PLAYER ...... 159 8. AAC BUILDING BLOCK SPECIFICATIONS ...... 160
8.1. DETAILED REQUIREMENTS ...... 160 8.2. FUNCTIONAL ASPECTS OF THE AAC BUILDING BLOCK ...... 163 8.2.1. AUTHENTICATION ONLY SCENARIO ...... 164 8.2.2. ACCESS TO THE USER-RELATED PROTECTED RESOURCES ...... 164 8.2.3. ACCESS TO THE NON USER-RELATED PROTECTED RESOURCES ...... 165 8.2.4. RESOURCE ACCESS AUTHORIZATION ...... 165 8.3. AAC BUILDING BLOCK ARCHITECTURE AND IMPLEMENTATION ...... 165 8.3.1. AAC ARCHITECTURE...... 165 8.3.2. AAC IMPLEMENTATION ...... 167 8.4. DOCUMENTATION AND USER MANUAL ...... 167 8.4.1. REGISTERING THE CLIENT APP ...... 167 8.4.2. REGISTERING NEW PERMISSION SCOPES ...... 170 9. LOGGING BUILDING BLOCK SPECIFICATIONS ...... 172
D2.9 – Report on the WeLive Open Service Layer v1 page 3
9.1. DETAILED REQUIREMENTS ...... 172 9.2. FUNCTIONAL ASPECTS OF THE LOGGING BUILDING BLOCK ...... 173 9.2.1. LOGGING MODEL ...... 173 9.2.2. LOG ANALYSIS ...... 174 9.3. LOGGIN BUILDING BLOCK ARCHITECTURE AND IMPLEMENTATION ...... 174 9.3.1. LOGGING ARCHITECTURE ...... 174 9.3.2. LOGGING BB DEPLOYMENT ...... 175 9.4. REST API ...... 175 10. REGISTRY BUILDING BLOCK SPECIFICATION ...... 179 11. QUERY MAPPER SPECIFICATION ...... 181
11.1. JSON DATA SOURCES ...... 182 11.2. CSV DATA SOURCES ...... 184 11.3. SPARQL DATA SOURCES ...... 185 11.4. RELATIONAL DATA SOURCE MAPPING ...... 187 11.5. REST API ...... 187 12. SOCIAL WRAPPER SPECIFICATIONS ...... 189 13. WEB SCRAPER SPECIFICATION ...... 194 14. CONCLUSIONS ...... 196 15. ABBREVIATIONS ...... 197 16. REFERENCES ...... 198 17. COMMENTS FROM EXTERNAL REVIEWERS ...... 199 17.1. CNS ...... 199 17.2. DNET ...... 200
ILLUSTRATIONS
Figure 1 – Open Service Layer in WeLive Architecture ...... 12 Figure 2 – WeLive Building Block metamodel ...... 14 Figure 3 – Swagger documentation of the REST API ...... 25 Figure 4 – Example of method documentation with Swagger ...... 26 Figure 5 – Method response shown in the Swagger interface ...... 26 Figure 6 – REST Client utility showing call to example method ...... 27 Figure 7 – Response from the method call ...... 27 Figure 8 – Example showing the structure of the required JSON data ...... 27 Figure 9 – Documentation for the WeLive’s Controller API...... 28 Figure 10 – Main WeLive Controller page for guest users ...... 29 Figure 11 – WeLive Controller UI flow chart ...... 45 Figure 12 – WC.INT.4 sequence diagram ...... 46 Figure 13 – WCUI.INT.2 sequence diagram ...... 47 Figure 14 – Deployment diagram for WeLive Controller ...... 48 Figure 15 – WeLive Controller UI: City selection ...... 49 Figure 16 – WeLive Controller UI: Sign Up form ...... 50 Figure 17 – WeLive platform login main menu ...... 50 Figure 18 – Login through WeLive CAS server ...... 51 Figure 19 – WeLive Controller UI: Tool selection ...... 51 Figure 20 – WeLive Support form ...... 52 Figure 21 – Mashup Editor ...... 57 Figure 22 – Example of a mashup developed through the Visual Composer ...... 58
D2.9 – Report on the WeLive Open Service Layer v1 page 4
Figure 23 – Visual Composer complete actors hierarchy ...... 72 Figure 24 – Diagram of the use cases related to services and opendata management ...... 73 Figure 25 – Diagram of the use cases related to projects management ...... 74 Figure 26 – Diagram of the use cases related to projects management ...... 75 Figure 27 – Diagram of the use cases related to the workgroup management ...... 76 Figure 28 – Sequence diagram for VC.UC.1 "View items catalogue"...... 92 Figure 29 – Sequence diagram for VC.UC.2 "View item details" ...... 93 Figure 30 – Sequence diagram for VC.UC.3 "Search items"...... 94 Figure 31 – Sequence diagram for VC.UC.4 "Import opendata" ...... 94 Figure 32 – Sequence diagram for VC.UC.5 "Import service" ...... 95 Figure 33 – Sequence diagram for VC.UC.6 "Delete item" ...... 95 Figure 34 – Sequence diagram for VC.UC.7 "Change item visibility" ...... 96 Figure 35 – Sequence diagram for VC.UC.8 "Create mashup project" ...... 97 Figure 36– Sequence diagram for VC.UC.9 "Create mockup project" ...... 97 Figure 37 – Sequence diagram for VC.UC.10 "View project details" ...... 98 Figure 38 – Sequence diagram for VC.UC.11 "Edit project details" ...... 99 Figure 39 – Sequence diagram for VC.UC.12 "Delete project" ...... 100 Figure 40 – Sequence diagram for VC.UC.13 "Add members" ...... 101 Figure 41 – Sequence diagram for VC.UC.14 "Add comment"...... 101 Figure 42 – Sequence diagram for VC.UC.15 "View projects list" ...... 102 Figure 43 – Sequence diagram for VC.UC.16 "View gadget details" ...... 102 Figure 44 – Sequence diagram for VC.UC.17 "Configure gadget" ...... 103 Figure 45 – Sequence diagram for VC.UC.18 "Export gadget" ...... 103 Figure 46 – Sequence diagram for VC.UC.19 "Export HTML App" ...... 104 Figure 47 – Sequence diagram for VC.UC.20 "Publish gadget" ...... 104 Figure 48 – Sequence diagram for VC.UC.21 "Edit mashup project"...... 105 Figure 49 – Sequence diagram for VC.UC.22 "Get recommendations" ...... 106 Figure 50 – Sequence diagram for VC.UC.23 "Edit mockup project"...... 107 Figure 51 – Sequence diagram for VC.UC.24 "Publish screenshot"...... 108 Figure 52 – Sequence diagram for VC.UC.25 "Create workgroup"...... 108 Figure 53 – Sequence diagram for VC.UC.26 "View workgroup list" ...... 108 Figure 54 – Sequence diagram for VC.UC.27 "View workgroup details" ...... 109 Figure 55 – Sequence diagram for VC.UC.28 "Assign Modeler to workgroup" ...... 109 Figure 56 – Sequence diagram for VC.UC.29 "Edit workgroup" ...... 109 Figure 57 – Sequence diagram for VC.UC.30 "Delete workgroup" ...... 110 Figure 58 – Sequence diagram for VC.UC.31 "Create idea workgroup" ...... 110 Figure 59 – Sequence diagram for VC.UC.32 "View modelers list" ...... 111 Figure 60 – Sequence diagram for VC.UC.33 "View modeler details" ...... 111 Figure 61 – Sequence diagram for VC.UC.34 "Enable/Disable modeler" ...... 112 Figure 62 – VC.INT.1 sequence diagram ...... 112 Figure 63 – VC.INT.2 sequence diagram ...... 113 Figure 64 – VC.INT.3 sequence diagram ...... 113 Figure 65 – VC.INT.4 sequence diagram ...... 114 Figure 66 – VC.INT.5 sequence diagram ...... 115 Figure 67 – VC.INT.5 sequence diagram ...... 115 Figure 68 – Deployment diagram for Visual Composer ...... 117 Figure 69 – Service catalogue ...... 118 Figure 70 – Service details page ...... 118 Figure 71 – Search into WeLive Marketplace ...... 119 Figure 72 – Create a new mashup project ...... 119 Figure 73 – Mashup projects list ...... 120 Figure 74 – Mashup editor and its functional areas ...... 120 Figure 75 – Modal window that shows the service operations ...... 121 Figure 76 – How to link the output of a source element to the input of a target element ...... 122 Figure 77 – How to bind an input object to an input parameter of a service element ...... 122 Figure 78 – Property panel of the selected service element ...... 123
D2.9 – Report on the WeLive Open Service Layer v1 page 5
Figure 79 – Modal window that shows the opendata resources ...... 123 Figure 80 – Query Editor ...... 124 Figure 81 – How to set the input parameters of operators ...... 127 Figure 82 – Mashup example ...... 127 Figure 83 – Mashup outcome ...... 128 Figure 84 – Create a new mockup project ...... 128 Figure 85 – Mockup projects list ...... 129 Figure 86 – Mockup editor and its functional areas ...... 129 Figure 87 – How to configure a form ...... 130 Figure 88 – How to configure a form input ...... 131 Figure 89 – Modal window that shows the list of mashups inputs ...... 131 Figure 90 – How to add a new input to the form ...... 132 Figure 91 – How to configure a table ...... 133 Figure 92 – Insert parameters to invoke mashups ...... 133 Figure 93 – Select the array to bind with the table ...... 134 Figure 94 – Table and its functional areas ...... 134 Figure 95 – How to configure a span element ...... 135 Figure 96 – Binding of a field with a span element ...... 135 Figure 97 – Mockup preview example ...... 136 Figure 98 – WeLive Player use case diagram ...... 148 Figure 99 – WLP Profile view and update sequence diagram ...... 151 Figure 100 – WLP Sequence Diagram for the app search ...... 152 Figure 101 – WeLive user authentication ...... 153 Figure 102 – City based list of WeLive apps...... 154 Figure 103 – App ordering ...... 154 Figure 104 – App details ...... 155 Figure 105 – Community info about app ...... 155 Figure 106 – Protected resource access ...... 164 Figure 107 – AAC Building Block Architecture ...... 166 Figure 108 – Client app registration ...... 167 Figure 109 – Client app overview ...... 168 Figure 110 – Client app resources and permissions ...... 169 Figure 111 – Client app tokens ...... 169 Figure 112 – New service registration ...... 170 Figure 113 – Service details (ID, name, description) ...... 170 Figure 114 – Service mapping definition ...... 171 Figure 115 – Logging BB Architecture ...... 174 Figure 116 – Logging BB deployment diagram ...... 175 Figure 117 – Registry BB APIs ...... 180 Figure 118 – Searching and import flow performed by the Visual Composer ...... 180 Figure 119 – Query Mapper internal architecture ...... 181 Figure 120 – JSON data source example mapping and relational tables ...... 183 Figure 121 – CSV data source example mapping and relational tables ...... 185 Figure 122 – SPARQL endpoint mapping description ...... 186 Figure 123 – SQL to SPARQL translation example ...... 187 Figure 124 – Structure of relational database mapping file...... 187 Figure 125 – Query mapper REST API ...... 188
TABLES
Table 1 – Open Service Layer requirements ...... 11 Table 2 – Building block ...... 16 Table 3 – PublicServiceApplication class ...... 17 Table 4 – Entity class ...... 17 Table 5 – Terms Conditions class ...... 18
D2.9 – Report on the WeLive Open Service Layer v1 page 6
Table 6 – StandardLicense class ...... 18 Table 7 – CustomLicense class ...... 18 Table 8 – InteractionPoint class ...... 19 Table 9 – REST Web Service IP class ...... 19 Table 10 – SOAP Web Service IP class ...... 19 Table 11 – TechnicalConstraint class...... 20 Table 12 – SecurityMeasure class ...... 21 Table 13 – TechnicalConstraint class...... 21 Table 14 – ProtocolConstraint class ...... 21 Table 15 – OriginConstraint class...... 22 Table 16 - AuthenticationMeasure class ...... 23 Table 17 – IdentityProvider class ...... 23 Table 18 – PermissionAuthorization class ...... 24 Table 19 – IdentityProvider class ...... 24 Table 20 – Macro-requirements of the WeLive Controller UI ...... 31 Table 21 – WeLive Controller detailed requirements ...... 42 Table 22 - WeLive Controller use cases ...... 44 Table 23 – WeLive Controller and data protection requirements ...... 55 Table 24 - WeLive Controller functional tests ...... 56 Table 25 – Macro-requirements elicitation of the Visual Composer included in [1] ...... 60 Table 26 – Visual Composer detailed requirements ...... 71 Table 27 – Visual Composer Actor/Permissions table ...... 73 Table 28 - Visual Composer use cases ...... 91 Table 29 – Mapping between VC interoperability demands and the respective APIs ...... 116 Table 30 – Complete list of the built-in mashup operators ...... 126 Table 31 – Visual Composer ethical and data protection requirements...... 138 Table 32 - Visual Composer functional tests...... 141 Table 33 – Macro-requirements elicitation of the WeLive Player included in [1] ...... 144 Table 34 – WeLive Player detailed requirements ...... 148 Table 35 – WeLive Player use cases ...... 150 Table 36 – WeLive Player ethical and data protection requirements...... 158 Table 37 - WeLive Player functional tests...... 159 Table 38 – AAC building block detailed requirements...... 163 Table 39 – Logging building block detailed requirements ...... 173 Table 40 – Registry BB APIs ...... 179
D2.9 – Report on the WeLive Open Service Layer v1 page 7
1. EXECUTIVE SUMMARY The role of the Open Service layer is to help public administrations, companies and citizens to realize new added value services on top of, and beyond, the Open Data layer with the provisioning of complete solutions able to support the development, publication and distribution. More specifically, the objective of this layer in the WeLive architecture is to allow factorizing the IT capabilities offered by a city into components, and to make sure that they can be easily accessed, reused and combined with each other to give place to composite services and apps. In order to fulfil this role and objective, the Open Service layer provides instruments of different kind: Building Block model: building blocks are the concept defined by WeLive to capture the components corresponding to elementary IT capabilities of the city; their model is hence the core concept to realize both the factorization of the IT capabilities and their composition in higher value services and apps. Tools: these are the instruments that support an easy access, reuse and combination of the capabilities exposed as building blocks IT capabilities. More precisely, the Visual Compose allows users and developers to match up different building blocks and components into new services and apps; the WeLive Controller allows developer to access the APIs that expose the functionalities of the WeLive platform and to access all the other tools within the WeLive ecosystem through a graphical interface; the WeLive Player allows end-users to access the services and apps realized through WeLive and available on the Marketplace. Core Building Blocks: these are building blocks that expose internal functionalities of the WeLive platform in a way that is compliant with the Building Block model, so that these functionalities can be exploited to compose new services and apps, together with the other components.
This deliverable describes the first realization of the Open Service layer and of all the instruments. This first version, realized at the end of the first project year, will be used during the first pilot phase and will then be revised during the second project iteration. The deliverable provides a detailed description of model, tools and core building blocks, covering functional aspects, requirements and the use cases; analysing technical aspects, interoperability issues and deployment solutions; providing specifications and user manuals; and addressing ethical and data protection issues when necessary.
D2.9 – Report on the WeLive Open Service Layer v1 page 8
2. INTRODUCTION The purpose of this deliverable is to present the first version of the outcomes of Task 2.3, namely of the WeLive Open Service layer. The version of the Open Service layer and of the tools described in this deliverable is the one, which will be used during the first pilot phase. The goal of this layer in the WeLive architecture is to allow factorizing the IT capabilities offered by a city into components that can be easily accessed, reused and combined with each other to give place to composite urban services. The core of this layer is the specification of the Building Block (BB) model: indeed, BBs are the concept defined by WeLive to capture the components corresponding to elementary IT capabilities of the city. The Open Service layer also encompasses the following tools: WeLive Controller; Visual Composer (VC) and WeeLive Player. In addition to these tools, the Open Service layer includes the description of a first set of Core Building Blocks, namely of BBs that expose internal functionalities of the WeLive platform in a way that is compliant with the BB model, so that these functionalities can be exploited to compose new services and apps, together with the other BBs. The core functionalities exposed in this way are: Authentication and Authorization; Logging; Registry; Query Mapper; Social Wrapper; Web Scraper.
The Open Service layer and its tools have been defined on the basis of the approach and requirements defined by the consortium in the deliverable D1.5 [1]. Moreover, the functionalities supported by the components of the Open Service layer are also coherent the guidelines provided by the WeLive framework reference architecture defined in Task 1. For each component, the report includes a formalization of detailed requirements, use case model, dynamic model and architectural aspects using the Unified Modelling Language standard [2]. The actual software components defining the Open Service layer are part of the companion deliverable D2.11 [3]. The present report is structured in the following sections: Section 3 summarizes the high level architecture of WeLive Open Service layer included in D1.5 [1]. Section 4 is devoted to the specification of the building block model and of the different elements that define the life-cycle of BBs: definition; invocation and execution; access policies and security profile; authoring, ownership, and licensing aspects; service level agreements. Sections 5, 6 and 0 cover the three tools in the Open Service layer, namely the WeLive Controller, Visual Composer, and WeLive Player respectively. Each section describes the functional aspects, the detailed requirements and the use cases for the tool; it discusses interoperability aspects, the technology and architecture choices for implementation and deployment. The user manual for the tool is also included in the section. Finally, ethical and data protection issues are discussed and test results are reported. Sections from 8 to 13 describe the core building blocks, listed previously in this Introduction; the structure of these sections is the same of the one used for the tools. Finally, section 14 provides conclusions about task T2.3 and about this report.
D2.9 – Report on the WeLive Open Service Layer v1 page 9
3. OVERVIEW OF WELIVE OPEN SERVICE LAYER AND HIGH LEVEL ARCHITECTURE 3.1. REQUIREMENTS The role of the Open Service Layer is to help public administrations, companies and citizens to realize new added value services on top of the Open Data layer with the provisioning of complete solutions able to support the development, publication and distribution. This functionality is captured by the OSF.1 requirement represented in [1] and refined with the requirements OSF.2 – OSF.6 .
ID Name Description
OSF.1 Management of This requirement implies the capability to manage building blocks the lifecycle of building blocks, namely the registration of new building blocks, their update and cancellation, their discovery and their usage.
OSF.2 Reference model for This requirement is about the definition of a building blocks reference model, consisting a set of interfaces and restrictions that every component must fulfil in order to be a WeLive compliant building block. It is also about the development of libraries and code stubs to ease the development of WeLive compliant building blocks.
OSF.3 Exposition of datasets This requirement is about the definition and as building blocks implementation of a mechanism for exposing the datasets of the Open Data Layer as WeLive compliant building blocks.
OSF.4 Exposition of open This requirement is about the possibility for a APIs as building blocks developer to register a new building block by providing an open API that is conformant to the building block reference model.
OSF.5 Core building blocks This requirement is about the expose as WeLive compliant building blocks of the core functionalities offered by the WeLive framework. These include logging functionalities (see also CBB.1), user authentication functionalities (see also CBB.2), building block and app registry functionalities (see also CBB.3), and functionalities provided by the reasoning engines implemented by the WeLive framework (e.g., Decision Engine).
OSF.6 Composite building This requirement is about the capability of blocks developers to expose as new building blocks the services obtained by combining existing building blocks. In particular, this capability shall be made available for the services defined with the Virtual Composer.
D2.9 – Report on the WeLive Open Service Layer v1 page 10
Table 1 – Open Service Layer requirements
These requirements aim at providing the support for the WeLive vision in different phases. First, the common reference model for the WeLive building blocks will ensure that the relevant assets of the city and of the companies are made publicly available, are represented, and access in a standardized manner. This will make easier the discovery and access of the building blocks by the citizens (e.g., in case of Public Service Applications) and 3 rd parties (e.g., open APIs and datasets) thus fostering also the new idea creation and making the overall ecosystem sustainable. Second, the core components and functionalities provided by the platform and relying on this common reference model will facilitate the management of the building blocks life-cycle. Third, the possibility to turn the new ideas into a working solution through the building block composition , aims at supporting the process of co-creation and co-innovation. The use of a unified reference model makes it possible for the resulting collaboration to become publicly available and accessible in no time. 3.2. ARCHITECTURE The requirements and the vision described in the previous section are refined in the following architecture (Figure 1). The Open Service Layer is incorporated in the WeLive platform in different dimensions, namely deployment and execution view, the management view and the innovation view. From the deployment and execution perspective, the contribution of the Open Service Layer is twofold. First, it defines the reference model for the WeLive building blocks and in particular for the applications and services exposed with the open APIs. These applications, deployed to one of the hosting environments offered by the platform are provided with the standard descriptions and interfaces, describing both general- purpose information (e.g., providers and authors, license info, classification) and technical information (e.g., the supported protocols and formats, security constraints). Second, the Open Service Layer provides a set of key infrastructure components, referred to as Core Building Blocks. These components expose generic operations to be used by both by the platform itself and by the new building blocks. In particular, the following core building blocks are provided: Authentication and Authorization Control (AAC) building block that provides the functionality of user authentication as well as of the structured access control for the building blocks exposed as open APIs. Logging building block that allows for collecting the information regarding the platform-level and application-level events. Registry building block that exposes the operations for accessing and managing the information of available building blocks, datasets and applications. Query Mapper building block for facilitating the access and information retrieval regarding the open datasets. Web Scrapper and Social Wrapper building blocks that allow for retrieving the relevant information from the web and social networks.
D2.9 – Report on the WeLive Open Service Layer v1 page 11
Figure 1 – Open Service Layer in WeLive Architecture
From the management perspective, the Open Service Layer is represented as follows. The WeLive-compliant building blocks (i.e., the components that adhere to the unified reference model specification) can be immediately published and distributed through WeLive Marketplace. In particular, the publication is made available either through the Marketplace UI or programmatically, using the Marketplace API, and relies on the building block specification documents exposed by the building block itself or by the corresponding hosting environment. Note that not only the open APIs are published in this way, but also the open dataset exposed by the WeLive ODS component and the public service applications. This common representation drastically simplifies the process of the building block management, which is performed by the WeLive Controller component. Finally, also the resulting public service applications (being mobile apps, web applications, or Open Social gadgets) are captured using the standard reference model. This allows for the realization of the WeLive player, component which has a goal of discovering and delivering these applications to the final user, taking into account his profile and interest. Providing the Visual Composer component, the Open Service Layer contributes to the WeLive architecture from the innovation, and more importantly from the co-innovation perspective. This component allows for collaborative creation of the composite building blocks defined on top of the other existing ones (open APIs or datasets). In these regards, Visual Composer plays a role of another hosting environment, as it provides also the execution engine of the composite building blocks. The resulting artefacts are then exposed by the Visual Composer through the standard reference model and published directly to the Marketplace.
D2.9 – Report on the WeLive Open Service Layer v1 page 12
3.3. DEPLOYMENT As anticipated in Section 3.2, the deployment of building blocks takes place using the building block hosting environment . The realization of the hosting environment may vary; a hosting environment may be a general- purpose platform offered, e.g., in the form of Platform-as-a-Service or Infrastructure-as-a-Service, or a specialized platform, where the artefacts of a particular nature are delivered (as it is in case of Visual Composer). With respect to the standard building block specification, the hosting environment deployment may be organized in different ways. In a base scenario, the hosting environment offers only the execution platform, while the specification model is provided by the building block itself. To assist the developers in such a scenario, Open Service Layer provides a set of templates and guidelines that minimize the effort of defining the specification. These templates, for example provide the instruments for the API documentation annotations, as well as the libraries for the specification generation and exposure on top of that. In an advanced scenario, the hosting environment exposes the specification model on behalf of the building block deployed. This specification is generated using the metadata providing within the hosting environment (e.g., regarding the authorship, licensing, service offering, etc) and the interface specification adopted by the hosting environment (e.g., in case when all the hosted building block have the same API imposed by the environment). Finally, an intermediate scenario is possible, where the building block API is hosted in some base environment, and another component is used to expose the WeLive-compliant specification for the published API.
D2.9 – Report on the WeLive Open Service Layer v1 page 13
4. OPEN SERVICE LAYER SPECIFICATIONS This document presents the building block specification notation used to describe the different aspects of the WeLive building blocks. The specification aims at addressing the requirement OSF.2 of [1]. The specification aims at representing, in particular, the following elements of the building block life-cycle: the building block definition (name, description, publisher, etc.); the building block invocation and execution (interaction points); the building block access policies (security profile); the building block authoring, ownership, and licensing aspects; the building block service level agreements.
The specification relies on the Linked USDL notation as a formal specification language for the definition of these elements. 4.1. BB METAMODEL The building block (hereafter, BB) specification comprises a set of profiles used to characterize different aspects of the BB representation and execution. The aim of the specification is to capture the BB characteristics, that may be required: when the users (BB clients, citizens, developers) search for relevant components to build new applications upon; during the application execution, when a BB has to be accessed and invoked providing the unambiguous definition of access policies and invocation protocols.
Figure 2 – WeLive Building Block metamodel
The WeLive BB metamodel is represented in Figure 2. In this model any BB is abstracted with the Building Block class and the corresponding subclasses are provided for each of the specific BB types (service, dataset,
D2.9 – Report on the WeLive Open Service Layer v1 page 14
or public applciation). Together with the generic properties (such as title and description, provider, classification), the metamodel defines the Legal Conditions that characterize the licensing and usage terms aspects. To provide the description of the BB execution, the Interaction Point class defines the corresponding technical properties, such as the access protocol in case of a service, the interface definition, and the data formats. Finally, the Security Measure and the Service Level Profile classes describe the BB access policies and the service offering characteristics of the building blocks. The specification notation is RDF-based and relies on a wide range of existing ontologies. Throughout this document the RDF XML format will be used for the example and for the formal definition of the metamodel elements. In the following sections, we provide the detailed definition of the metamodel ontology, based on the Linked USDL specification. 4.2. CORE PROFILE The core BB profile is used to define the main description properties of the building block: type, title, description, categories, etc. The key classes that constitute this profile are Artifact (and its subclasses), Entity, and the Legal Conditions. 4.2.1. BUILDING BLOCKS The Artifact class is an abstraction of various building block types. The following are common information both for datasets, services, and public service application. 4.2.1.1. Artifact class
Attribute Description Note
dcterms:title BB title
dcterms:created BB creation date
dcterms: abstract BB short description
dcterms:description BB long description
welive: pilot BB pilot reference defining the reference area (city, province), where the BB is deployed and localized
foaf:page BB web page where could be described the extended description, business model, installation manual, tutorials and developer’s guide, and so on. dcterms:type → Artifact's application type: This field allows the decision skos:Concept Web service; engine to fastly classify the Open Social Gadget; artifacts. Android application; Web Application; OSGi Bundle
D2.9 – Report on the WeLive Open Service Layer v1 page 15
Dataset
tag:tag A tag associated to the current This field allows the decision Artifact (multiplicity 0:n). engine to fastly catch the topics focused by the artifact. Property Description Note
hasBusinessRole → En ty BB business entities involved list such as author, owner or provider(1,n). hasLegalCondition → Legal Legal conditions about BB usage Condition hasInteractionPoint → BB interaction point Defines the interaction profile of Interaction Point the BB. hasServiceOffering → Service Level Agreement list [1:n] Defines the SLA profile of the BB. Service Offering hasSecurityMeasure → BB security measure Defines the security profile of the Security Measure BB. uses → Ar fact Other artifacts used by the instances of this class Table 2 – Building block
Note that this class is abstract: different types of the building blocks are represented with the corresponding subtypes of the BB. 4.2.1.2. Building Block class The BuildingBlock class is an abstraction of a generic BB. The class may define the dependency declarations with respect to other BBs or datasets. Currently contains no attributes or properties on its own. The example below represents a definition of the Bike Sharing information REST Web Service. The declaration defines that bikesharing is a BuildingBlock of type WebService.
D2.9 – Report on the WeLive Open Service Layer v1 page 16
Attribute Description Note
dcterms:url The URL of the public service application Table 3 – PublicServiceApplication class
4.2.2. BUILDING BLOCK ENTITIES The Entity class is used to characterize the relation between the building blocks and the various stakeholders: owners, providers, authors being physical persons or organizations. This class also represents the role it plays with respect to the BB. The role the entity plays with respect to BB may be: Provider Author Owner
Attribute Description Note
dcterms:title Entity title
foaf:page Web page of the entity (if applicable) foaf:mbox Contact mail box of the entity
Property Description Note
businessRole → The role of the entity BusinessRole Table 4 – Entity class
The example below defines a provider entity for the enclosing building block.
rdf:resource ="http://www.welive.eu/ns/welive-core#Provider" /> D2.9 – Report on the WeLive Open Service Layer v1 page 17
4.2.3. LEGAL CONDITIONS The legal conditions aim at capturing the aspects of the BB usage related to the licensing, authorship, etc. Specifically, the condition may be represented with the License class.
Attribute Description Note
dcterms:title BB title
dcterms:description BB long description
Table 5 – Terms Conditions class
Note that this class is abstract: the specific conditions and license should be instantiated instead. Currently contains no attributes or properties on its own. Note that this class is abstract: the specific license should be instantiated instead. Currently contains no attributes or properties on its own. Note that this class is abstract: the specific license should be instantiated instead. The licenses are devided in Standard Licenses and Custom Licenses . The Standard Licenses refer to the commonly used license types, such as AST, MIT, GPL, LGPL, and various versions.
Attribute Description Note
schema:url URL of the license with the complete license definition. Table 6 – StandardLicense class
Attribute Description Note
schema:url URL of the license with the complete license definition. Table 7 – CustomLicense class
The example below defines a provider entity for the enclosing building block.
4.2.4. INTERACTION PROFILE
D2.9 – Report on the WeLive Open Service Layer v1 page 18
The interaction profile defines the means and protocols to be used for the invocation and communication with the building blocks. These protocols vary for different types of BBs. Besides, the interaction profile allows for expressing specific constraints and restrictions to be applied to the interaction. 4.2.4.1. Interaction Point class The key element of the interaction profile is the Interaction Point class. This element represents an actual access and invocation of a building block. On a technical level this could translate into calling a Web Service operation, endpoint/format of the dataset, or properties of the service application. Besides, the interaction point may be associated to the technical constraints, such as preconditions, postconditions, and monitoring. Optionally, it is possible to characterize the input/output parameters of the interaction point in order to support the analysis of the building block. In order to provide the formal description
Attribute Description Note
dcterms:title Interaction point title
dcterms:description Interaction point long description
welive:metadata The interaction point metadata endpoint. schema:url The interaction point endpoint. May vary for different types of the artifacts (service endpoint, dataset url, or the mobile app installation URL) Property Description Note
hasConstraint → Interaction point constraints (1,n). TechnicalConstraint Table 8 – InteractionPoint class
The two subclasses of the InteractionPoint class define different Web service types: REST Web services and the SOAP Web services. For these subclasses, the specification of the interface specification URL should be provided.
Attribute Description Note
welive:wadl The WADL interface specification URL. Table 9 – REST Web Service IP class
Attribute Description Note
welive:wsdl The WADL interface specification URL. Table 10 – SOAP Web Service IP class
The following example provide the description of the REST Web service interaction point for the above service example. The service endpoint declares the metadata and WADL endpoint.
D2.9 – Report on the WeLive Open Service Layer v1 page 19
4.2.4.2. TechnicalConstraint class In case an interaction point is a subject of certain usage restrictions, such as pre- or post-conditions, these restrictions may be represented with the TechnicalConstraint declaration. Specifically, the technical constraint defines the type of the constraint, the language used to express the constraint conditions, and the text of the constraint. Currently, the three types of the constraint are supported: Pre-condition : the constraint defines the execution context properties to hold before the interaction takes place; Post-condition: the constraint defines the execution context properties to hold after the interaction takes place;
Monitoring: a generic property that is expected to be observed when the interaction takes place.
Attribute Description Note
dcterms:language The constraint language
swrl:body Formal definition of the constraint condition Property Description Note
type → RuleType The type of the constraint (pre -, post-condition, monitoring) Table 11 – TechnicalConstraint class
4.3. SECURITY PROFILE The WeLive Security Profile aims at characterizing the security aspects of the BB access. Specifically, the profile captures the following security dimensions of the BB access and communication: Communication : the constraints and properties related to the communication channel of the building block (e.g., usage of the HTTPS protocol only). Authentication : the constraints and properties related to the identification of the user or client, which aims at interacting with the BB. The service may or may not require authentication, may refer to specific authentication protocols, and even identity providers. Authorization : when applicable, the BB may require not only that the accessing party is authenticated
D2.9 – Report on the WeLive Open Service Layer v1 page 20
within the flow, but is also authorized to perform certain operation. For example, the access to the medical data service may be granted only to clients that have obtained a corresponding permission from the user that owns the data.
When defined, the security constraints are obligatory for the requesting party. Failure to satisfy any of the specified requirements may result in a blocked access operation. The security requirements of these types are captured with the corresponding subclasses of the SecurityMeasure class. The instances of this class declare the measure descriptions, while the specific properties pertaining to the various categories are defined in the subclasses.
Attribute Description Note
dcterms:title Interaction point title
dcterms:description Interaction point long description
Table 12 – SecurityMeasure class
Note that the security profile may be further extended in order to support more specific security features in different dimensions. 4.3.1. COMMUNICATION MEASURES Communication security measures deal with the characteristics of the communication channel enforced by the building blocks. Specifically, the two types of communication channel properties may be declared: the Protocol constraints and the Origin constraints. Each communication measure may refer to zero or more such constraints.
Property Description Note
withProtocol → The protocol restrictions for the ProtocolConstraint secure communication (0,n) withOrigin → The caller origin restrictions for OriginConstraint the secure communication (0,n) Table 13 – TechnicalConstraint class
4.3.1.1. ProtocolConstraint class The ProtocolConstraint add restrictions to the underlying protocols to be used for the BB interactions (e.g., to use HTTPS protocol only). In the current version of the specification the restriction is defined with the protocol reference (literal value).
Attribute Description Note
protocol Protocol type
Table 14 – ProtocolConstraint class
The following example demonstrates the declaration of the requirement to use HTTPS protocol for the service communication.
D2.9 – Report on the WeLive Open Service Layer v1 page 21
4.3.1.2. OriginConstraint class The OriginConstraint add restrictions to the origin of the caller to be used for the BB interactions (e.g., to use a specific whitelist of addresses or the same domain in case of Web service calls; to have the same signing identity when a mobile app is called). In the current version of the specification, the restriction is defined with the origin definition (literal value).
Attribute Description Note
origin Origin restriction
Table 15 – OriginConstraint class
4.3.2. AUTHENTICATION MEASURES Authentication security measures deal with the restrictions on the BB access. Specifically, the authentication measure defines who can access authenticates (the user, the client application, or both), how the BB can be accessed (i.e., the authentication protocol to use, such as CAS [4], OpenID [5], OAuth2 [6], etc), and where to authenticate the user (i.e., which identity provider to exploit; applies only in case of subset of protocols).
Property Description Note
withIdentityProvider → The identity providers allowed for IdentityProvider that BB. If more than one provider is specified, the authentication should take place with any of those. If non specified, any provider is accepted. protocolType → The supported authentication The protocols to be supported ProtocolType protocol for the authentication. here include That is, the characterization of the OAuth2 credentials to be passed when the OpenID service is invoked: whether to use CAS header authentication tokens, Shibboleth [7] specific cookies, etc. Basic Authentication
accessType → AccessType The type of the access allowed: If none specified, any access type user is allowed. client
D2.9 – Report on the WeLive Open Service Layer v1 page 22
both
Table 16 - AuthenticationMeasure class
4.3.2.1. IdentityProvider class The IdentityProvider class instances define the references to the various authentication providers available locally (e.g., authentication systems of a specific city or an organization) and globally (e.g., WeLive central authentication provider, or de-facto standard providers such as Google+, Facebook, Twitter, etc). The identity provider is characterized with its unique identifier.
Attribute Description Note
dcterms:identifier Identity provider unique identifier
Table 17 – IdentityProvider class
The following example demonstrates an authentication measure that relies on the Oath2.0 protocol with the user-only access and the Google+ as identity provider.
4.3.3. AUTHORIZATION MEASURES Authorization security measures deal with the access control policies, when it is necessary to grant different access permissions to different users (or user groups). In the current version of the specification and the implementing infrastructure the authorization measures can be defined with the permission-based policies. That is, the BB authorization measure may declare a set of permissions that should be obtained by the calling party before the BB invocation. These permissions are defined using the Permission class. Note that the permissions referred to by the BB specifications, should correspond to the permissions defined within the underlying authorization control infrastructure (AAC). In this way, the BB local access controller can interact with the AAC API in order to validate the provided credentials of the accessing party against the required ones.
D2.9 – Report on the WeLive Open Service Layer v1 page 23
Property Description Note
requires → Permission Different permissions that should be provided with the passed credentials in order to access the described artefact. It is possible to specify many permissions for the measure; in this case all the permissions should be provided. Table 18 – PermissionAuthorization class
4.3.3.1. Permission class The Permission declares the specific access restriction for the BB: only the clients that have been explicitly authorized (by the user) to perform the specific operation or retrieve the specific information. The identity provider is characterized with its unique identifier, and optionally with the title and description.
Attribute Description Note
dcterms:identifier Permission unique identifier
dcterms: title Name of the permission
dcterms:description Textual description of the permission Table 19 – IdentityProvider class
The following code represents the example of the permission-based authorization measure. This measure requires that the permission to access the basic user profile is provided (“profile.basicprofile.me” scope identifer).
D2.9 – Report on the WeLive Open Service Layer v1 page 24
5. CONTR OLLER SPECIFICATIONS The Controller component in WeLive provides a common access point to all the functionality of the platform, not only for human users, thanks to its web interface, but also to applications through the provided API. Therefore, the controller has two different parts: API: used by project components to achieve their integration into a common solution and, in addition, by external applications that use the functionalities offered by the solution. Web UI: that provides an integrated access to all the different components of the project offering an entry point for end users: administrators, councils, citizens, developers, etc. 5.1. REST API The Controller API is a REST interface that exposes the core functionality of the platform and its components, including not only the functionality that is specific for each integrated component but also the new one that emerges as part of the project. The API follows the following conventions to organize and name the available actions: GET. Actions that retrieve information and do not perform any modification in the server. They can receive optional parameters to modify the query. POST. Actions that add new resources to the server. They require receiving a body containing the posted data, usually in JSON format. Following the REST conventions, POSTs are performed to the entity URL. PUT. As a POST action, they require to send data in the request body, however, in this case they are used to modify an existent entity, which means that the modified object must already exist in the server DELETE. These actions are used to remove existing entities from the server. They always require the identifier of the resource to delete.
The usage of a REST API provides an easier way to use and understand access point for project integration and for third-party developers. In addition to the typical API calls, WeLive's API provides a Swagger interface, which documents the methods and its parameters. The Swagger interface enables developers to discover and test the API methods in an interactive manner.
Figure 3 – Swagger documentation of the REST API Next, two examples on using the Swagger interfaces are described, in order to show the usage of the Swagger API.
D2.9 – Report on the WeLive Open Service Layer v1 page 25
Mapping creation This example shows the creation of a mapping through a POST call to the method /dataset/{datasetID}/resource/{resourceID}/mapping. As can be seen in figure, two path parameters (datasetID and resourceID) and a JSON object in the body of the request are required. The IDs of datasets can be retrieved through the method /ods/dataset/all, and the IDs of the resources of a dataset can be retrieved through the method /ods/dataset/{datasetID}. The specification of the mapping is detailed in the documentation of the project. In the following image, the usage of the Swagger interface can be seen in Figure 4, while the response of the method execution is shown in Figure 5.
Figure 4 – Example of method documentation with Swagger
Figure 5 – Method response shown in the Swagger interface
D2.9 – Report on the WeLive Open Service Layer v1 page 26
Resource creation For creating a resource, the method /ods/dataset/{datasetID}/resource is provided. This method requires the ID of the dataset in which the resource is going to be created in the path of the URL, a form with three fields in its body ( packageDict , upload and fileInfo ), and the Authorization header, as can be seen in Figure 6. This figure shows how the API can be called using and external REST client, in this this case a plugin for Google Chrome that eases the testing during application development.
Figure 6 – REST Client utility showing call to example method The results from the call are shown in Figure 7, while in this case, the client will fill the fileInfo JSON automatically. The structure of the required JSON is shown in Figure 8. In this case, only the fields name and fileName are mandatory.
Figure 7 – Response from the method call
Figure 8 – Example showing the structure of the required JSON data
D2.9 – Report on the WeLive Open Service Layer v1 page 27
Documentation In addition to the Swagger interface, the API has a proper documentation built within Sphinx documentation generator. In this documentation, explanations about all provided methods can be found, companied by some illustrative examples, as can be seen in Figure 9.
Figure 9 – Documentation for the WeLive’s Controller API.
5.2. CONTROLLER UI 5.2.1. FUNCTIONAL ASPECTS OF THE CONTROLLER The WeLive Controller User Interface is the main web portal from which the WeLive end-user enters the WeLive ecosystem and accesses all the other WeLive web-based tools.
D2.9 – Report on the WeLive Open Service Layer v1 page 28
Figure 10 – Main WeLive Controller page for guest users
Specifically, the WeLive Controller operation can be divided in the next functions: WeLive Portal. The WeLive controller acts as the web portal to the WeLive ecosystem. This way, the first web pages announcing the WeLive Ecosystem are part of the WeLive Controller. Presentation of the WeLive capabilities to the end-user. As the first contact of the end-user with the WeLive ecosystem, the WeLive Controller constitutes a showcase for the target, functions, capabilities and terms of use of WeLive, both in an informational and advertising way. Gateway to user management. As most WeLive tools are available both for guest and registered users, the WeLive Controller offers the following functions related to user management:
Access to a subset of WeLive tools for guest (not logged) users. Gateway to AAC’s login menu, for already registered users to log in the WeLive ecosystem. Gateway to registration form, for new users to register in the WeLive ecosystem. The registration is propagated to all the WeLive tools that require user management. Gateway to Citizen Data Vault’s account management. Log out of the WeLive environment. Language selection. City selection. The capabilities of the WeLive ecosystem can only be accessed at the same time for a single city by a single user. Registered users already have a city linked to their account, but guest users must select a city as a first step to enjoy the WeLive capabilities. Support. The WeLive Controller offers hints for its use as long as a form to report any question or issue related to WeLive ecosystem. Gateway to other WeLive web tools. From the WeLive Controller, the user can access the other WeLive web tools, preserving its user session. These tool are:
Open Innovation Area WeLive Marketplace
D2.9 – Report on the WeLive Open Service Layer v1 page 29
Open Data Stack Citizen Data Vault Visual Composer Analytics Dashboard Logging anonymous activity. The WeLive Controller will log anonymous user activity by simply registering the number of times that an event takes place (without any connection to the corresponding user session). The events registered are the following:
Number of times that every city has been selected. Number of times that the support form has been submitted. Number of times every tool has been selected. 5.2.2. DETAILED REQUIREMENTS AND USE CASE MODEL 5.2.2.1. DETAILED REQUIREMENTS The following table summarizes the macro-requirements of the WeLive Controller UI.
ID Name Description
WCUI.1 Portal display The WeLive Controller UI must be the main page of the project domain. It must show only the information and options that correspond to every guest or registered user.
WCUI.2 User registration The WeLive Controller UI must allow new users to register in the WeLive ecosystem by their own. The registration must be suitably propagated to the other WeLive web tools requiring registration.
WCUI.3 User log in / log out Already registered users must be able to log in the WeLive ecosystem using multiple providers. A user logged in the WeLive Controller UI must remain logged in the other WeLive web tools. A user logged in the other WeLive web tools must remain logged in the WeLive Controller UI. A user logged out of any WeLive web tool must be logged out of every other WeLive web tool, including the WeLive Controller UI. A logged user must be able to access its personal information through the Citizen Data Vault.
WCUI.4 Language selection A guest user must be able to view the WeLive Controller UI information in different languages. A registered user must view the WeLive Controller UI in the main language configured in his/her account.
D2.9 – Report on the WeLive Open Service Layer v1 page 30
WCUI.5 City selection A registered user must access the WeLive Controller UI already set up for his/her city. A guest user must be required to select his/her preferred city, which will be valid until the user selects another one.
WCUI.6 WeLive support form A form must be available to the user for reporting any issues or suggestions to the WeLive Team.
WCUI.7 Redirection to other The WeLive Controller UI must provide working Welive web tools links to the other WeLive web tools, once a city has been selected.
WCUI.8 Logging anonymous The WeLive Controller UI must log anonymous user activity activity by registering the number of times that every event takes place.
WCUI.9 Legal notices The WeLive Controller UI must display any legal notice related to the WeLive Consortium, the user data privacy and the use of Cookies.
Table 20 – Macro-requirements of the WeLive Controller UI In the tables below, the detailed requirements are reported.
ID WCUI.1.1
Name Portal accessibility
Requirement Type Functional
Description The WeLive Controller UI must be accessible from most modern web browsers supporting HTML5/CSS3 through HTTPS at the root folder of the project domain. When trying to access through an HTTP unsecure connection, an automatic redirectionto HTTPS must be performed.
Rationale Being the WeLIve Controller the main web portal of the WeLive ecosystem, it must be easily accessible for any user from any modern web browser.
Fit Criterion The user accesses the WeLive Controller UI from a modern HTML5 web browser by (Measurable) entering the main domain of the project. The user is able to access the WC UI via HTTPS without specifying a protocol or by specifying HTTP or HTTPS, with or
without a trailing ‘/’. The corresponding web page is displayed suitably in last versions of Internet Explorer/Edge, Safari, Chrome and Firefox; both desktop and mobile versions. The page content is web responsive.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
D2.9 – Report on the WeLive Open Service Layer v1 page 31
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.1.2
Name Portal content consistency
Requirement Type Functional
Description The WeLive Controller UI displayed content must be consistent with the user depending on whether he/she is a guest or his/her role if it logged in. It must also consistent with user interaction.
Rationale Guest users have limited access to some features. Logged users have some options (city or language) already determined in their account. Logged users may have different access privileges depending on their role.
Fit Criterion Guest users must always select a city as a first step before selecting a tool. (Measurable) Logged users must skip the city selection step, as a city is already associated to their profile. Guest users must be able select a language of their choice. All the content of the WeLive Controller UI will then appear in the language of their choice. Logged users see the content in the language associated to their profile, so they have the language selection disabled. Only guest (not logged users) can see the “sign up” and “login” options. Logged users see “log out” and a link to their CDV profile instead. Only admin users have access to the server control panel.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Users with different profiles.
Author TECNALIA team.
D2.9 – Report on the WeLive Open Service Layer v1 page 32
Revision V1.0, 29/03/2016
ID WCUI.2
Name User registration
Requirement Type Functional
Description A user can register in the WeLive ecosystem from scratch through the WeLive Controller UI.
Rationale Regular users must be able to register in the WeLive ecosystem by theirselves, as WeLive is a tool opened to the citizen.
Fit Criterion A non-existing user must be able to fill and submit the registration form. (Measurable) After submitting the form, the user must receive a mail with his/her new password. The new user must then be able to log in the WeLive ecosystem with his/her new credentials.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints A user, as identified by his/her e-mail, can only be registered once. (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Non-registered user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.3.1
Name User log in
Requirement Type Functional
Description A registered user can log in the WeLive ecosystem using multiple providers.
Rationale Once a user has been registered in the WeLive ecosystem, he/she must be able to log in the platform through the easier way.
Fit Criterion A registered user can log in the WeLive ecosystem only with the correct (Measurable) credentials.
D2.9 – Report on the WeLive Open Service Layer v1 page 33
The user can log in directly through the WeLive login form or through Google and Facebook providers. Once the user has logged in, he/she remain logged in the different WeLive web tools. A logged user can access his/her personal data in the CDV.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The CAS Single Sign On must be suitably implemented in every module. (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Registered user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.3.2
Name User log out
Requirement Type Functional
Description A logged user can log out the WeLive ecosystem.
Rationale A logged user must be able to log out the platform to protect his/her data and allow another user to log in.
Fit Criterion A logged user can log out the WeLive ecosystem. (Measurable) Once the user has logged out from the WeLive Controller UI, he/she is logged out from every WeLive web tool.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The CAS Single Sign Out must be suitably implemented in every module. (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Logged user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
D2.9 – Report on the WeLive Open Service Layer v1 page 34
ID WCUI.4
Name Language selection
Requirement Type Functional
Description The displayed information must be shown in the language desired by the user.
Rationale The user must understand the data displayed.
Fit Criterion A logged user accesses the WeLive Controller UI in the language specified in (Measurable) his/her account. Guest users can select the language in which to display the content of the WeLive Controller UI (between the languages corresponding to the cities involved and English). The page content is updated suitably.
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.5
Name City selection
Requirement Type Functional
Description Guest users must be able to select the city for which they want to use the WeLive tools. Logged users must access the WeLive tools for the city configured in their account.
Rationale Every WeLive service must be linked to a city.
Fit Criterion Guest users must always select a city before selecting any tool. The city must be (Measurable) associated since then to any user action until a new city is selected. Logged users must not have the option to select a city, so they must directly access the tool selection page for their configured city.
D2.9 – Report on the WeLive Open Service Layer v1 page 35
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.6
Name WeLive support form
Requirement Type Functional
Description Any user must be able to report an issue or request through a suitable form.
Rationale Attending to user requests is required to improve users’ satisfaction and as a feedback for the WeLive ecosystem progress and mainteinance.
Fit Criterion The fields of the form that can be determined from the session are automatically (Measurable) filled. The user submits correctly the form related to an issue or a request. An e-mail is received in the associated e-mail address with the fields specified in the form.
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors WeLive support desk. Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.1
D2.9 – Report on the WeLive Open Service Layer v1 page 36
Name Redirection to Open Innovation Area
Requirement Type Functional
Description Redirection from WeLive Controller UI to the Open Innovation Area.
Rationale As the main WeLIve entry point, the WeLive Controller UI must link the WeLive Open Innovation Area.
Fit Criterion The user is redirected to the Open Innovation Area when selecting the (Measurable) corresponding link. The user session (logged user or city selected) is propagated to the Open Innovation Area.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.2
Name Redirection to the WeLive MarketPlace
Requirement Type Functional
Description Redirection from WeLive Controller UI to the WeLive MarketPlace.
Rationale As the main WeLIve entry point, the WeLive Controller UI must link the WeLive MarketPlace.
Fit Criterion The user is redirected to the WeLive MarketPlace when selecting the (Measurable) corresponding link. The user session (logged user or city selected) is propagated to the WeLive MarketPlace.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
D2.9 – Report on the WeLive Open Service Layer v1 page 37
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.3
Name Redirection to the Open Data Stack
Requirement Type Functional
Description Redirection from WeLive Controller UI to the WeLive Open Data Stack.
Rationale As the main WeLIve entry point, the WeLive Controller UI must link the WeLive Open Data Stack.
Fit Criterion The user is redirected to the WeLive Open Data Stack when selecting the (Measurable) corresponding link. The user session (logged user or city selected) is propagated to the WeLive Open Data Stack.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.4
Name Redirection to the City Data Vault
Requirement Type Functional
Description Redirection from WeLive Controller UI to the WeLive City Data Vault.
D2.9 – Report on the WeLive Open Service Layer v1 page 38
Rationale As the main WeLIve entry point, the WeLive Controller UI must link the WeLive City Data Vault.
Fit Criterion The user is redirected to the WeLive Open Data Stack when selecting the (Measurable) corresponding link or clicking on the username. The user session (logged user or city selected) is propagated to the WeLive City Data Vault.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.5
Name Redirection to the Visual Composer
Requirement Type Functional
Description Redirection from WeLive Controller UI to the WeLive Visual Composer.
Rationale As the main WeLIve entry point, the WeLive Controller UI must link the WeLive Visual Composer.
Fit Criterion The user is redirected to the WeLive Open Data Stack when selecting the (Measurable) corresponding link or clicking on the username. The user session (logged user or city selected) is propagated to the WeLive Visual Composer.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
D2.9 – Report on the WeLive Open Service Layer v1 page 39
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.6
Name Redirection to the Analytics Dashboard
Requirement Type Functional
Description Redirection from WeLive Controller UI to the WeLive Analytics Dashboard.
Rationale As the main WeLIve entry point, the WeLive Controller UI must link the WeLive Analytics Dashboard.
Fit Criterion The user is redirected to the WeLive Open Data Stack when selecting the (Measurable) corresponding link. The user session (logged user or city selected) is propagated to the WeLive Analytics Dashboard.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.7.7
Name Redirection to the Admin Control Panel
Requirement Type Functional
Description Redirection from WeLive Controller UI to the Admin Control Panel, only for administrators.
Rationale Administrators must have access to the Admin Control Panel.
Fit Criterion The Admin Control Panel link is only available for administrator users. (Measurable) The administrator user is redirected to the Admin Control Panel when selecting the
D2.9 – Report on the WeLive Open Service Layer v1 page 40
corresponding link. The user session is propagated to the Admin Control Panel.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Administrator user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
ID WCUI.8
Name Logging anonymous activity
Requirement Type Functional
Description The WeLive Controller UI activity must be logged anonymously to monitor the platform activity.
Rationale The WeLive Controller UI activity must be logged to monitor the platform activity. These logs must be anonymous according to the user confidentiality agreement.
Fit Criterion Check that the logging dashboard is correctly updated as the final user perform (Measurable) the next operations: Select a city Select a WeLive tool Send a support form
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
D2.9 – Report on the WeLive Open Service Layer v1 page 41
ID WCUI.9
Name Legal notices
Requirement Type Functional
Description Display the applicable legal notices.
Rationale According to the data protection rules in the EU, everyone has the right to the protection of data. These notices will inform the user about the way his/her data is going to be protected.
Fit Criterion Request the acceptation of the data protection agreement during the registration (Measurable) process. Show “Terms of use” under demand. Request the acceptation of the Cookie policies when a new user accesses the WeLive Controller.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Final user.
Author TECNALIA team.
Revision V1.0, 29/03/2016
Table 21 – WeLive Controller detailed requirements
5.2.2.2. USE CASE MODELS As the requirements of the WeLive have been separated in many simple and singular ones, they are going to be demonstrated through only three complete but easily understandable use cases: A complete guest user tour. New user registration. A registered user tour since log in.
WCUI.UC.1 Guest user tour Covered requirements WCUI.1.1, WCUI.1.2, WCUI.4, WCUI.5, WCUI.6, WCUI.7.1, WCUI.7.2, WCUI.7.3, WCUI.7.4, WCUI.7.5, WCUI.7.6, WCUI.7.7, WCUI.8, WCUI.9 Short description A regular complete tour of a guest user, checking the available options until the selection any other WeLive tool.
D2.9 – Report on the WeLive Open Service Layer v1 page 42
Actors Guest user.
Preconditions -
Main flow 1. The user gives his/her consent to the use of cookies. 2. The user selects a language other than English (Spanish). 3. The user selects a city (Bilbao). 4. The user submits a support request form (let’s suppose that the user wants to request support for another city). 5. The user selects the tool Open Innovation Area. Secondary flows Select other languages. Select other cities. Select other tools.
Postconditions The user obtains the expected results. An e-mail with the support request arrives to the e-mail address configured for the corresponding WeLive support desk. In the logging dashboard should be registered: One record per city selection. One record perWeLive tool selection. A record corresponding to a support request.
WCUI.UC.2 New user registration
Covered requirements WCUI.1.1, WCUI.1.2, WCUI.2
Short description Registration of a new user.
Actors Unregistered user. Preconditions -
Main flow 1. A new user fills the registration form. 2. The user submits the registration form. Secondary flows Error cases: The user does not complete all the required fields. The user specifies an already existing e-mail.
Postconditions The user receives a mail with his/her new password. The user is able to log in using his/her new password. The new user record has been created in all the required WeLive web platforms (AAC and CDV mainly).
D2.9 – Report on the WeLive Open Service Layer v1 page 43
WCUI.UC.3 Registered user tour
Covered requirements WCUI.1.1, WCUI.1.2, WCUI.3.1, WCUI.3.2, WCUI.4, WCUI.5, WCUI.7.4, WCUI.7.8
Short description Registered user regular tour since login.
Actors Registered user. Preconditions The user must be registered.
Main flow 1. A registered user logs in using his/her credentials. 2. The user visits his/her CDV profile. 3. The user logs out from the platform. Secondary flows Login through the different providers. Login as an administrator and access the control panel.
Postconditions The user gets logged in the WeLive Controller and the other WeLive tools. Once logged in, the user shows the content for his/her corresponding city and in his/her corresponding language. The user accesses his/her user profile in the CDV. The user gets logged out from the WeLive Controller and the other WeLive tools.
Table 22 - WeLive Controller use cases
5.2.3. DYNAMIC MODEL AND INTEROPERABILITY DEMANDS 5.2.3.1. FLOW CHART The navigation flow through the WeLive Controller UI is represented by the flow char of the Figure 11. The schema is quite simple: A guest user must select a city before selecting a tool. An unregistered user must register in the WeLive ecosystem, unless he /she wants to access as a guest user. A registered user must log in the WeLive ecosystem to enjoy the advantages of his/her account. A logged user enters directly the tool selection page, as he/she is already associated to a city. From the tool selection page, the user can select another WeLive tool and leave the WeLive Controller flow. The language selection option and the support form have been omitted due to their simplicity.
D2.9 – Report on the WeLive Open Service Layer v1 page 44
Figure 11 – WeLive Controller UI flow chart
5.2.3.2. INTEROPERABILITY WITH OTHER WELIVE COMPONENTS The WeLive Controller UI (WC) interacts with some other WeLive components acting as a client of the corresponding REST API’s. All the related calls travel encrypted through a SSL connection and require a valid HTTP Basic Authentication. WCUI.INT.1 : During the user registration process, the WeLive Controller must propagate the user data to other WeLive tools. The procedure is the following: 1. Register the user in the AAC, as it is the tool in charge of authorization an authentication. The AAC generates the CCUserID, the unique ID of the new user for the entire WeLive ecosystem. 2. Register the user in the platform running the WeLive Controller itself (no interaction needed). 3. Register the user in the Citizen Data Vault, as it is the tool in charge of the personal data of the citizen. 4. Register the user in the Visual Composer. A requirement of the Visual Composer itself. The following sequence diagram depicts WCUI.INT.1 interactions.
D2.9 – Report on the WeLive Open Service Layer v1 page 45
Figure 12 – WC.INT.4 sequence diagram
Int. demand Id Provider Tool Method Signature WCUI.INT.1 AAC POST /aac/extuser/create CDV POST /cdv/api/datasource/operation/adduser Visual Composer POST /visualcomposer/webservice/register/user
WCUI.INT.2 : Like every WeLive tool, the WeLive Controller must log the user interaction anonymously. It requires interaction with the Logging BB. It must log the following events: Number of times that every city has been selected. Number of times that the support form has been submitted. Number of times every tool has been selected. The following sequence diagram depicts WCUI.INT.2 interactions (the process is the same for all events).
D2.9 – Report on the WeLive Open Service Layer v1 page 46
Figure 13 – WCUI.INT.2 sequence diagram
Int. demand Id Provider Tool Method Signature WCUI.INT.2 Logging BB POST /welive.logging/log
5.2.4. TECHNOLOGY CHOICE REASONING AND USAGE DESCRIPTION FOR IMPLEMENTATION Liferay Portal Liferay Portal 1 is an open source web platform primarily used to power corporate intranets and extranets, as it can widely be used to build websites, portals, mobile apps and web services, in a very similar way to a standard Content Management System. Liferay is Java-based and runs on any computing platform that running the Java Runtime Environment and most popular Java application servers. Apart from Java (the language Liferay is written in, and thus the most common language supported by the platform), it also support PHP and Ruby portlets. Liferay portals consist basically on sites (one site per portal, as one Liferay instance supports multiple sites) , every one composed by multiple pages. Although the basic configuration of a portal is performed through configuration files and a web control panel, its main operation is controlled through plugins. These plugins can be developed ad-hoc or purchased at the Liferay App Store when they have a generic purpose. A portal supports six different types of plugins out-of-the-box: Portlets: Small web applications that run in a portion of a web page. Themes: Plugins that define the look-and-feel of pages. Layout templates: Plugins that define the arrangement of the different portlets on a page. Hooks: Plugins that allow hooking into the portal core functionality. Webs: Regular Java EE modules designed to work with the portal such as ESB (Enterprise Service Bus) and SSO (Single Sign-On). Ext: Ext plugins allow using internal APIs or even overwriting files provided in the Liferay core. Liferay is distributed under the GNU Lesser General Public License 2 and optional commercial license.
1 https://www.liferay.com 2 http://www.liferay.com/web/bryan.cheung/blog/-/blogs/liferay-adopting-the-lgpl-license
D2.9 – Report on the WeLive Open Service Layer v1 page 47
Liferay CE has been selected as the main framework for various of the WeLive web tools. That is the case of the WeLive Controller UI, the Open Innovation Area, the Marketplace and the Analytics Dashboard. It could be said that it has been used for most web tools, except those which can take advantage of specific features of other platforms or previous developments. Liferay features adapt in a proper way to the WeLive ecosystem, which can be conceived as a very specific purpose portal. The different tools (or even specific functions of the different tools) can be isolated in different plugins and arranged in different pages, while sharing many elements such as page headers and footers, themes that assure a common look-and-feel or the user session. This way, the Live Controller UI has been designed as a full-page Liferay MVC portlet that runs in the first page of the main site of the Liferay instance. The different HTML views involved are loaded into the portlet frame, according to a state managed by a Java controller. The Liferay session maintains the user session, while it also stores the selections performed by guest users. The user registration form can be conceptually considered as part of the WeLive Controller. It has been developed as a Liferay hook that overrides the default registration form provided by Liferay. Materialize CSS Materialize 3 is a modern and responsive open-source front-end web framework based on Google’s Material Design 4. It is available as a CSS3/Javascript library. It is also available in SASS format to supply more control over CSS components to developers. Materialize is distributed under MIT License 5. Materialize support has been added to the WeLive’s Liferay main theme, so that it allows a quick development of a responsive interface for the WeLive Controller in compliance with the mockup design of the tool. Central Authentication Services (CAS) Central Authentication Services (CAS) is a Single Sign-On protocol used to permit a user to access the different WeLive web tools while providing his/her credentials only once. 5.2.5. ARCHITECTURE AND DEPLOYMENT DIAGRAM OF THE CONTROLLER
Figure 14 – Deployment diagram for WeLive Controller
3 http://materializecss.com/ 4 https://www.google.com/design/spec/material-design/introduction.html 5 https://github.com/Dogfalo/materialize/blob/master/LICENSE
D2.9 – Report on the WeLive Open Service Layer v1 page 48
The WeLive Controller UI is provided as two Liferay plugins: An MVC portlet. This portlet controls the main operation of the WeLIve Controller UI. A registration hook that overrides the default Liferay’s registration process. Those plugins present at the same time some dependencies with the theme used for the Liferay’s UI. Those plugins are run by a Liferay Portal 6.2 CE GA5 instance, the same that runs the Open Innovation Area, the Marketplace and the Analytic Dashboard. The instructions about the installation of Liferay can be found at https://dev.liferay.com/discover/deployment . Once Liferay has been installed WAR files that package the plugins are deployed through the Liferay’s Admin Control Panel. 5.2.6. DOCUMENTATION AND USER MANUAL 5.2.6.1. Access The WeLive Controller UI can be accessed through any modern HTML5 web browser currently in the address https://dev.welive.eu/ . 5.2.6.2. Language selection Guest users can change the language anytime through the “Language” selector of the header. 5.2.6.3. City selection Guest users can select the city of their interest.
Figure 15 – WeLive Controller UI: City selection
D2.9 – Report on the WeLive Open Service Layer v1 page 49
5.2.6.4. Registering New users are allowed to register in the WeLive platform to save their preferences and get a higher level of interaction. This can be done through the form accessed through the “SIGN UP” button on the header.
Figure 16 – WeLive Controller UI: Sign Up form
A valid e-mail, the first and the last name are required. After the sign up process, the user will receive an e- mail with his/her new password. 5.2.6.5. Log in A registered user can log in through the “LOGIN” button in the header.
Figure 17 – WeLive platform login main menu
D2.9 – Report on the WeLive Open Service Layer v1 page 50
The user have three different providers available to login: Google, WeLive CAS server and Facebook.
Figure 18 – Login through WeLive CAS server
5.2.6.6. WeLive tool selection Once a user has selected a city (for guest users) or logged in (for registered users), a WeLive tool can be selected.
Figure 19 – WeLive Controller UI: Tool selection
D2.9 – Report on the WeLive Open Service Layer v1 page 51
5.2.6.7. Log out A logged user can log out the WeLive environment through the “LOGOUT” button in the header. 5.2.6.8. WeLive support For any issue or question, please fill the contact form available through Technical Support -> WeLive Support menu in the header. The corresponding WeLive support desk will answer as soon as possible.
Figure 20 – WeLive Support form
5.2.7. DATA PROTECTION RELATED REQUIREMENTS
Requirement Related questions Controller component
In a system like WeLive there is the Are the consent As specified in WCUI.9, the WeLive Controller UI requirement for the consent of the form processes design considers the next consent forms: individuals concerned. included in the A cookie consent form. This is displayed system design? the first time the user accesses the If a youngster of below 16 years Who is designing the Controller, in order to fulfil the EU wishes to use online services, the consent form and Cookie Law. service provider has to try to verify the terms of use for A user registration agreement. This that parental consent has been various user groups? agreement details the data protection given. clauses and the user rights. It must be checked in order to continue with the In addition the controller shall be registration process. able to demonstrate that consent A terms of use announcement, was given by the data subject to accessible from the page header under the processing of their personal demand.
D2.9 – Report on the WeLive Open Service Layer v1 page 52
data.
The system has to provide easy How are these Most personal data is isolated in the Citizen access to your own data, including requirements to be Data Vault (CDV). how their data is processed. This taken into account A fraction of this data is replicated in the WeLive information should be available in in the system design Controller UI, as the Liferay framework requires a clear and understandable way. and in various it (such as the user’s e-mail). building blocks and Further there is a right to applications? Personal data access is restricted to the user portability, facilitating the owning the data. transmission of personal data from The user can check, modify or even destroy one service provider. his/her personal profile from the CDV front-end.
Individuals have also a right to erase personal data and "to be forgotten". This enables subjects to require the removal, without delay, of personal data collected or published. Individuals have the right to know How is the system Does not apply to WeLive Controller. when your data has been hacked: and its various Companies and organisations must components to be notify the national supervisory monitored from this authority of serious data breaches viewpoint? as soon as possible so that users can take appropriate measures. Individuals have the right to object How is this feature Most personal data is isolated in the Citizen to the processing of personal data to be taken into Data Vaul t (CDV). relating to the public interest or to account in the A fraction of this data is replicated in the WeLive legitimate interests of a controller. system (citizen data Controller UI, as the Liferay framework requires This right covers the use of vault, decision it (such as the user’s e-mail). personal date for the purposes of engine and 'profiling'. analytics)? Analytics processed by the Analytics Dashboard (ADS) take information from the Logging (Common safeguards covering the Building Block, which does not process personal processing of personal data for information and even does not link its logs to archiving purposes where that is in any profile (it acts simply as a counter of the public interest and for scientific anonymous events). and historical research or statistical purposes.) Transfer of personal data outside This is to be taken The development infrastructure and its the EU: the regulation lays down when figuring out corresponding databases are located in the rules for transferring personal the business model Frankfurt (Germany, EU). data to third countries and and the hosting All the databases and their backups will be international organizations. environments. located in the EU. Transfer may take place provided
D2.9 – Report on the WeLive Open Service Layer v1 page 53
that a number of conditions and No data will be transferred to third parties. safeguards are met. The Act is based on “risk-based How is the overall The most private data of the user stored by the approach”: the stronger the risks security architecture platform is his address. This information is not of the activities for the personal of the WeLive? How mandatory and is only accessible by the user data, the more stringent the Is the privacy by himself through the CDV. obligations are. Processing design-approach The server infrastructure is hosted by Linode 6, sensitive data (including race, applied? (see also which ensures a high security level. health) is of a special concern. deliverable 5.3) Requirements include Privacy Only the services required by end-users are Impact Assessment and other available outside the platform infrastructure. measures needed to tackle risks. All the communications are forced through HTTPS/SSL 7using a server certificate dispatched Data protection safeguards are to by a recognised CA (Comodo 8).This configuration be built into products and services passes the more strict security tests 9. from the earliest stage of development (Data protection by All the server administrative tasks have place through SSH 10 and require superuser credentials. design and default). Such measures could consist inter alia of Databases are password protected and are not minimizing the processing of accessible outside the server infrastructure. personal data, pseudonymising Every WeLive module requires HTTP Basic personal data a.s.a.p, transparency authentication 11 over SSL when accessing data with regard to the functions and concerning a user from a service. This data is not processing of personal data, accessible outside the platform infrastructure. enabling the data subject to monitor the data processing, The user session is shared between WeLive enabling the controller to create modules in a secure way through the CAS 12 and improve security features. protocol . Every final user accessing non-general purpose information from a service requires OAuth 2.0 13 authentication and authorization.
Any processing of personal data in This is to be taken Does not apply to WeLive Controller. the context of the activities of an when figuring out establishment of a controller or a the business model processor is to be carried out in and the hosting accordance with regulation, environments. regardless of whether the
6 https://www.linode.com/security 7 https://www.openssl.org/ 8 https://ssl.comodo.com/wildcard-ssl- certificates.php?key5sk0=1907&key5sk1=6510add78e43fab19e7c7b46ab77907e9eb08d26 9 https://www.ssllabs.com/ssltest/analyze.html?d=dev.welive.eu&hideResults=on&latest 10 http://www.openssh.com/ 11 https://tools.ietf.org/html/rfc2617 12 https://jasig.github.io/cas/4.0.x/protocol/CAS-Protocol.html 13 http://oauth.net/2/
D2.9 – Report on the WeLive Open Service Layer v1 page 54
processing itself takes place within the Union or not. Responsibilities between controller of the data and the processor of the data have to be defined clearly. Table 23 – WeLive Controller and data protection requirements
D2.9 – Report on the WeLive Open Service Layer v1 page 55
5.2.8. FUNCTIONAL TESTS RESULTS OF THE CONTROLLER The following table shows the results of the functional tests performed against the use cases described in section 5.2.2.2
Test ID Name Mapped Date Tests results (Iteration #1) Date Tests results (Iteration #2) use cases (Iteration #1) (Iteration #2) (PASSED/PASSED WITH (PASSED/PASSED WITH RESERVE/NOT PASSED) RESERVE/NOT PASSED)
WCUI.FT.1 Guest user tour WCUI.UC.1 30/3/2016. PASSED WITH RESERVE 31/3/2016 PASSED WITH RESERVE The user gives his/her The user gives his/her consent to the use of cookies consent to the use of cookies not implemented yet not implemented The user submits a support yet request form (let’s suppose that the user wants to request support for another city) not working
WCUI.FT.2 New user registration WCUI.UC.2 30/3/2016. NOT PASSED 31/3/2016 PASSED I did not get mail after registration
WCUI.FT.3 Registered user tour WCUI.UC.3 30/3/2016. PASSED
Table 24 - WeLive Controller functional tests
D2.9 – Report on the WeLive Open Service Layer v1 page 56
6. VISUAL COMPOSER SPECIFICATIONS 6.1. FUNCTIONAL ASPECTS OF THE VISUAL COMPOSER According to the Description of Action [4], the Visual Composer is the WeLive framework tool delivered as a result of the tailoring of an existing asset (called Service Mashup Editor) coming from the CLIPS IP-ICT-PSP project [9]. The Visual Composer is a tool, included in the WeLive framework, which consists of a user friendly Visual Mashup Editor that offers a straightforward and intuitive metaphor inspired by already existing services such as IFTTT 14 or Atooma 15 to assemble new public services by combining several urban building blocks and datasets. The precise definition of building block and dataset is provided in [10].Usable by non-technical users, it will guide users through a wizard-based, intuitive, interface in the definition of mashups as a result of a composition of existing building blocks and datasets following a data workflow approach, similar to that followed by existing services such as Yahoo! Pipes. It will allow to "almost" every actor, living and working in the territory, to create new public services in order to overcome a specific and common need or just a personal one. It will guide users when interacting with the Marketplace and the Decision Engine in order to identify the right building blocks. Through the Visual Composer, the development process will not be monopolized by highly specialized companies, it will also be accessible to freelance developer or skilled amateurs.
Figure 21 – Mashup Editor
Indeed, the Visual Composer allows the creation of widgets compliant with the OpenSocial Gadget Specifications [11] and Web Applications (HTML5+CSS3) through the mash-up of the technological services (SOAP and REST Web Services) and Opendata in a graphical way and without high technical skills. Moreover, this tool also allows to easily draw the gadgets or applications mock-ups related to the mash-up services. Using a client-side visual interface, called Mockup Editor, the user can compose a mash-up by using the services and opendata already existing in her/his catalogues and combining them through a set of built-in operators. The output of this mash-up is rendered in a new complex service that is exposed by the Visual Composer and can be invoked from external applications.
14 IFTTT is an application that permits to create chains of conditional statements, which are triggered based on changes to third parties web services. 15 Atooma is an application that permits to authomatize common actions performed by the user who use the tool.
D2.9 – Report on the WeLive Open Service Layer v1 page 57
Using a client-side visual interface named Mockup Editor the user can compose a mock-up for her/his mash- up by using a set of built-in Web elements (HTML tags, players and maps) and combining them in order to create web pages. The output of this mock-up is rendered in a Web Application or OpenSocial gadget that can be exported and deployed in a Web Server or a Gadget Container.
Figure 22 – Example of a mashup developed through the Visual Composer
Within the Visual Composer, a mashup is the outcome obtained as a result of the dynamic integration of data coming from multiple data sources (e.g. datasets and building blocks). Starting from a mashup it is possible to develop new and more sophisticated public services starting from simpler components that can be accessed by APIs. A mashup project allows users to define the business logic of a mashup through a graphical dashboard. The dashboard includes a palette of tools that permit to mashup data coming from building blocks and datasets coming from the ODS. A mock-up represents the user interface of a new public service built as a mashup of datasets and building blocks. The user interface includes graphical elements such as text areas, labels, buttons, geocoding maps... A mock-up project allows users to define the layout of the widget (i.e. open social gadgets specifications, HTML5 files, CSS, JavaScript) associated with one or more mashup projects. The mock-up project includes a dashboard and a palette of elements that permit to design and model the user interface. Furthermore, every user belonging to a specific workgroup will be able to access to a set of shared services and open data. 6.2. DETAILED REQUIREMENTS AND USE CASE MODEL 6.2.1. DETAILED REQUIREMENTS
D2.9 – Report on the WeLive Open Service Layer v1 page 58
The following table summarizes the macro-requirements elicitation of the Visual Composer included in [1].
ID Name Description
VC.1 Building blocks Import This requirement ensures that a logged user is able to import a SOAP or a REST web service on her/his service catalogue. In fact, this requirement implies that the Visual Composer has to interact with the Marketplace to import already published building blocks.
VC.2 Open Data Import This requirement ensures that a logged user is able to import open datasets. In fact, this requirement implies that the Visual Composer has to interact with the Marketplace and the Open Data Stack (ODS) to import already published datasets.
VC.3 Workgroup A group of users can join a workgroup. All of them collaboration will be able to collaborate each other in order to management create both mash-up projects and mock-up projects. Furthermore, every user belonging to a specific workgroup will be able to access a set of shared services and open data.
VC.4 Mash-up dashboard The Mashup dashboard allows the user to create and edit a service Mash-up. In a service mash-up the user will be able to use the service and open data imported on her/his catalogues.
VC.5 Mock-up dashboard The Mock-up dashboard allows the user to create and edit a layout for a specific mash-up. Once a mock-up project is associated with a mash-up, the user will be able to graphically define a layout for the visualization of the mashup outcome.
VC.6 Marketplace interfaces Through a specific interface exposed by the management marketplace, the user should be able to import services directly published on the marketplace. Through a specific interface exposed by the visual composer, once the user created a mock-up project, she/he will be able to publish it into the marketplace as Open Social Gadget or web application.
VC.7 Artefacts publication Mock-ups are the user interface of final apps. They wrap one or more mash-ups, which represent data workflow compositions across distinct WeLive artefacts. Mashups can be understood as more complex building blocks. The publication of both mashups and mock-ups artefacts into the
D2.9 – Report on the WeLive Open Service Layer v1 page 59
Marketplace has to be possible from the Visual Composer. The user will publish the final mash-up artefact as a RESTful service. A new public service (i.e. the mashup artefact includes both mashup and mock-up projects) artefact will be published in two formats: a) HTML5+CSS3 applications and b) OpenSocial Gadgets.
VC.8 Artefacts In cooperation with the Decision Engine, the Visual recommendation Composer should offer users artefact recommendations (building blocks and datasets) which might be used in new composite building blocks and public service apps.
Table 25 – Macro-requirements elicitation of the Visual Composer included in [1] In tables below, the detailed requirements are reported.
ID VC.1.1
Name Web Service import
Requirement Type Functional
Description The user can import a SOAP or a REST web service on her/his Service Catalogue.
Rationale The visual composer has been thought as a component where the users can mashup outcomes of different web services. To do that, the user must import on her/his service catalogue the web services used in mashup projects.
Fit Criterion Once the user has performed the search described in VC.6.1, she/he can import a (Measurable) service in her/his catalogue by clicking on the relative Add to Catalogue button.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Authenticated users
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.1.2
Name Web Services management
D2.9 – Report on the WeLive Open Service Layer v1 page 60
Requirement Type Functional
Description The ‘Service Catalogue’ page of the Visual Composer shows the list of all imported web services (REST and SOAP services). From this list the user can access the ‘Service details’ page of a web service, delete it from the catalogue or change its visibility.
Rationale The user should have a place where she/he can manage all imported web services.
Fit Criterion Once the user logs in, she/he navigates the Visual Composer and finds the list of (Measurable) imported web services in the ‘Service Catalogue’ page.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Authenticated users
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.2.1
Name Opendata import
Requirement Type Functional
Description The user can import an opendata from a URL or from the Open Data Stack (ODS) on her/his Opendata Catalogue.
Rationale The visual composer has been thought as a component where the users can mashup outcomes of different opendata. To do that, the user must import on her/his opendata catalogue the opendata used in mashup projects.
Fit Criterion Once the user has performed the search described in VC.6.1, she/he can import an (Measurable) opendata in her/his catalogue by clicking on the relative Add to Catalogue button.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
D2.9 – Report on the WeLive Open Service Layer v1 page 61
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Authenticated users Open Data Stack
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.2.2
Name Opendata management
Requirement Type Functional
Description The ‘Opendata Catalogue’ page of the Visual Composer shows the list of all imported opendata. From this list the user can access the ‘Opendata details’ page of an opendata, delete it from the catalogue or change its visibility.
Rationale The user should have a place where she/he can manage all imported opendata.
Fit Criterion Once the user logs in, she/he navigates the Visual Composer and finds the list of (Measurable) imported web services in the ‘Opendata Catalogue’ page.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Authenticated user.
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.3.1
Name Workgroup management
Requirement Type Functional
Description The VC administrator can create a new workgroup and assign users to it. Users of the
D2.9 – Report on the WeLive Open Service Layer v1 page 62
same workgroup can share services/opendata and mash-up/mock-up projects.
Rationale Only the VC administrator should be able to manage workgroups or to assign users to them.
Fit Criterion Once the administrator logs in, she/he navigates the Administration Area of the Visual Composer and finds the ‘Workgroup management’ area. Then she/he can (Measurable) create a new workgroup from the ‘Create workgroup’ section or view the list of workgroups in the ‘Workgroup list’ section.
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints Only an administrator can manage workgroups. (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Administrator
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.3.2
Name Associate workgroups and projects to an idea
Requirement Type Functional
Description The Open Innovation Area can ask the Visual Composer to create a new project and then associate it to the idea(i.e. as a result of the implementation of the idea).
Rationale When the visual composer is used to implement an idea as a data mashup of different building blocks and datasets, two projects (mashup and mockup) and one workgroup is created in order to reflect the group of collaborators of the idea created in the Open Innovation Area.
Fit Criterion When the idea passes to the implementation phase, the Open Innovation Area sends to the Visual Composer all the information it needs in order to create a new (Measurable) workgroup, mashup and mockup project related to the idea.
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Open Innovation Area
D2.9 – Report on the WeLive Open Service Layer v1 page 63
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.4.1
Name Mash-up management
Requirement Type Functional
Description Every user can view ‘Mashup projects list’ page where all mashup projects are listed and can be managed: the user can create, delete or edit a project; the user can also add members and comments to the project.
Rationale A user should have a place where she/he can easily access to all her/his mashup projects, in order to be able to manage them.
Fit Criterion Once the user logs in, she/he navigates the project section of the Visual Composer and finds the list of all her/his mashup projects. By selecting a project in the list, (Measurable) she/he will be redirected to the project details page.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints Only the owner of the project can delete it or add members (Attainable)
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.4.2
Name Mash-up Editor
Requirement Type Functional
Description The Mashup Editor is the Visual Composer tool that allows the user to use services and open data imported on her/his catalogues in order to create a new mashup (i.e. a new complex service).
Rationale In order to ease the creation of a mashup, the user should have a visual tool that allows him to easily compose services and opendata through a set of built-in operators.
Fit Criterion By clicking on the ‘Edit Mashup’ button in the ‘Mashup Projects list’ page (or in the ‘Mashup Project details’ page), the user will be redirected to the Mashup Editor. (Measurable)
D2.9 – Report on the WeLive Open Service Layer v1 page 64
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints Only members of the projects can edit it (Attainable)
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.5.1
Name Mock-up management
Requirement Type Functional
Description Every user has at his disposal a ‘Mockup projects list’ page where all his mockup projects are listed and can be managed: the user can create, delete or edit a project; he can also add members and comments to the project or export it as HTML Application.
Rationale A user should have a place where he can easily access to all his mockup projects, in order to be able to manage them.
Fit Criterion Once the user logs in, she/he navigates the project section of the Visual Composer and finds the list of all his mockup projects. By selecting a project in the list, she/he (Measurable) will be redirected to the project details page.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints To create a mock-up project, at least one mash-up must be available in the Mashup (Attainable) project list. Only the owner of the project can delete it or add members
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.5.2
D2.9 – Report on the WeLive Open Service Layer v1 page 65
Name Mock-up Editor
Requirement Type Functional
Description The Mashup Editor is the Visual Composer tool that allows the user to graphically define a layout for the visualization of the mashup outcome.
Rationale In order to ease the creation of a graphical interface, the user should have a visual tool that allows him to easily compose a web page through a set of built-in components.
Fit Criterion By clicking on the ‘Edit Mockup’ button in the ‘Mockup Projects list’ page (or in the ‘Mockup Project details’ page), the user will be redirected to the Mockup Editor. (Measurable)
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints Only members of the projects can edit it (Attainable)
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.5.3
Name Open Social Gadget configuration
Requirement Type Functional
Description The user can configure a mockup project so that it can be exported or published as Open Social Gadget.
Rationale Once the user creates a new public service, she/he should be able to configure it as Open Social Gadget in order to download or publish it.
Fit Criterion By clicking on the ‘Edit Gadget’ button in the ‘Mockup Projects list’ page, the user will be redirected to the view where she/he can configure the gadget. (Measurable)
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints Only members of the projects can edit it (Attainable)
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler
D2.9 – Report on the WeLive Open Service Layer v1 page 66
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.5.4
Name HTML Application export
Requirement Type Functional
Description The user can export a mockup project as HTML Application. Related to the requirement VC.5
Rationale Once the user creates a new public service, she/he should be able to export it as HTML Application archive and then download it.
Fit Criterion By clicking on the ‘Export HTML project’ button in the ‘Mockup Projects list’ page, the download of the HTML Application archive will be started. (Measurable)
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints Only members of the projects can edit it (Attainable)
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.6.1
Name Artefacts search
Requirement Type Functional
Description Every user can search for interesting artefacts (i.e. services and opendata) published into the Marketplace and then import them. Related to the requirement VC.6
Rationale The user should be able to easily import services and opendata having no care about technical issues (i.e. WADL or WSDL description).
Fit Criterion The user navigates the ‘Data & Services’ area of the Visual Composer and clicks on Import Artefact . He will be redirected to the view where he will be able to search for (Measurable) specific services or opendata (by keyword) published into the Marketplace.
D2.9 – Report on the WeLive Open Service Layer v1 page 67
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints None (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Authenticated user Marketplace
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.7.1
Name Open Social Gadget publication
Requirement Type Functional
Description The user can publish a new public service (i.e. artefact that includes both mashup and mock-up projects) as OpenSocial Gadget into the WeLive Marketplace.
Rationale Once the user creates a new public service, she/he should be able to publish it into the Marketplace in order to be make it publicly available.
Fit Criterion The user navigates the ‘Mockup Projects list’ page of the Visual Composer and clicks on the Publish button of a specific project. She/he will be redirected to the (Measurable) Publication page where she/he can specify some details about the Open Social Gadget. By clicking on Publish button, the user will be redirected to the Artefact Definition Tool of the Marketplace where she/he completes the artefact description.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The user must have previously created a mock-up project in order to give place to a (Attainable) final public service. The user must have previously configured the gadget.
Difficulty 4 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler Marketplace
Author ENG team.
Revision V1.0, 22/12/2015
D2.9 – Report on the WeLive Open Service Layer v1 page 68
ID VC.8 16
Name Artefacts recommendation
Requirement Type Functional
Description In cooperation with the Decision Engine, the Visual Composer should offer users artefact recommendations (building blocks and datasets) which might be used in new composite building blocks and public service apps.
Rationale The Decision Engine is the WeLive component where rule-based recommendations about potential building blocks and datasets could be delegated by the VC. Such recommendations will be useful for users building a new mashup project.
Fit Criterion The user, navigating the Visual Composer, can see an area containing the building blocks and datasets recommended with the mediation of the Decision Engine. If the (Measurable) recommendations reasoned by the Decision Engine match the preference of the VC user, she/he can import the dataset/building block into the dashboard of a mashup project.
Customer 4 (Scale from 1=uninterested to 5=extremely pleased). satisfaction
Customer 3 (Scale from 1=hardly matters to 5=extremely displeased). dissatisfaction
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The architecture must foresee the presence of a decision engine. (Attainable) The current user must be able to see building blocks and datasets recommended by the decision engine.
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Modeler Decision engine
Author ENG team.
Revision V1.0, 22/12/2015
Below a list of further requirements not included in [1] is reported.
ID VC.9
Name Mockups voted by the WeLive users and linked with ideas
Requirement Type Functional
16 As VC.8 is already detailed, it is reported here as reported in [1] for commodity.
D2.9 – Report on the WeLive Open Service Layer v1 page 69
Description In order to let all welive users of the Open Innovation Area to comment and vote draft of mockups implemented with the Visual Composer, a specific functionality should be included in the mockup editor. Votes and comments should be provided in the details page of the idea related to the mashup and mockup projects.
Rationale It is useful to let welive users to comment and vote the drafts of mockups created through the visual composer. This way more appreciated mockups will be created.
Fit Criterion In one hand, the modeller, during the creation of a mockup, can publish one or more screenshots in order to be evaluated and commented by the welive users. In the (Measurable) other hand, Welive users, navigating the details page of the related idea (in the Open Innovation Area), can vote and comment the screenshots. The most user friendly mockup will be selected by the modeller as the final choice.
Customer 5 (Scale from 1=uninterested to 5=extremely pleased). satisfaction
Customer 3 (Scale from 1=hardly matters to 5=extremely displeased). dissatisfaction
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints - (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Open Innovation Area, Modeler
Author ENG team.
Revision V1.0, 22/12/2015
ID VC.10
Name Users and groups administration
Requirement Type Non Functional
Description The Administrator of the Visual Composers should be able to manage users and groups in the Visual Composer
Rationale -
Fit Criterion The user, when logged as ad administrator, can manage users and groups (Measurable)
Customer 4 (Scale from 1=uninterested to 5=extremely pleased). satisfaction
D2.9 – Report on the WeLive Open Service Layer v1 page 70
Customer 3 (Scale from 1=hardly matters to 5=extremely displeased). dissatisfaction
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints - (Attainable)
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Administrator
Author ENG team.
Revision V1.0, 22/12/2015
Table 26 – Visual Composer detailed requirements
6.2.2. ACTORS AND USE CASES Several actors interact with the Visual Composer: Administrator: She/he performs the actions related to the administration of the whole Visual Composer. Modeler: She/he performs the actions related to the creation and publication of mashup and mockup projects. Marketplace: It is a WeLive tool where building blocks, datasets and public services are published and then accessed by users and other WeLive tools. Decision Engine: It is the WeLive platform tool that provides recommendations of building blocks to the Visual Composer. Open Data Stack: It is the WeLive tool where opendata are stored and accessed by other WeLive tools Open Innovation Area: It is a WeLive tool where ideas are co-created and published. The Visual composer supports the implementation of ideas. Both Administrator and Modeler users must be authenticated into the WeLive platform in order to run the use cases described in section 6.2. In Figure 23 the VC complete actors hierarchy is shown.
D2.9 – Report on the WeLive Open Service Layer v1 page 71
Figure 23 – Visual Composer complete actors hierarchy
Table 27 includes the association of actors to permissions within the Visual Composer. Actors Permissions
Administrator To manage all VC registered users To enable/disable a user (both Administrator and Modeler) To delete a Modeler user To add a new VC Administrator To manage workgroups To create/delete workgroups To assign a Modeler user to one or more workgroups To manage services and opendata with public visibility
Modeler To manage his/her own services and opendata (Citizen, Academic To import/delete services and opendata Representative, To change services and opendata visibility Business To manage mashup projects Representative, Civil Servant) To create/edit/delete a project To comment a project To add members to project To manage mockup projects
D2.9 – Report on the WeLive Open Service Layer v1 page 72
To create/edit/delete a project To comment a project To add members to project To export a project as HTML Application To publish a project into the Marketplace as Open Social Gadget
Marketplace None Decision Engine None Open Data Stack None Open Innovation Area To create a new workgroup Table 27 – Visual Composer Actor/Permissions table 6.2.3. Use Case Models Figure 24 depicts the Visual Composer use cases diagrams related to services and opendata management.
Figure 24 – Diagram of the use cases related to services and opendata management
Figure 25 and Figure 26 depict the Visual Composer use cases diagrams related to services and the projects management.
D2.9 – Report on the WeLive Open Service Layer v1 page 73
Figure 25 – Diagram of the use cases related to projects management
D2.9 – Report on the WeLive Open Service Layer v1 page 74
Figure 26 – Diagram of the use cases related to projects management
Figure 27 depicts the Visual Composer use cases diagrams related to users and workgroups management.
D2.9 – Report on the WeLive Open Service Layer v1 page 75
Figure 27 – Diagram of the use cases related to the workgroup management
The following are the main use cases of the Visual Composer:
VC.UC.1 View items catalogue Covered requirements VC.1.2, VC.2.2
Short description In the VC ‘Data & Services’ page the Authenticated user can find a list of all visible items (services or opendata). Actors Authenticated user.
Preconditions None Main flow The Authenticated user requires the service/opendata catalogue. The system responds to the user with a list of all visible items, i.e. Items imported by the user (only if the user is a modeler) Items with workgroup visibility (only if the user is a modeler) Items with public visibility Secondary flow -
Postconditions The authenticated user can see the catalogue of items
VC.UC.2 View item details
D2.9 – Report on the WeLive Open Service Layer v1 page 76
Covered requirements VC.1.2, VC.2.2
Short description The VC provides a page where all the item (service or opendata) information are available.
Actors Authenticated user. Preconditions A least one item is visible to the user.
Main flow The Authenticated user requires the details page of the imported item. The system responds with a page where all the information about the selected item are listed in a user-friendly manner. Secondary flow -
Postconditions The authenticated user can see item details
VC.UC.3 Search items Covered Requirements VC.6.1 Short description The Authenticated user makes a search of the items (service/opendata) published into the Marketplace by typing the keywords in the search bar. Actors Authenticated user Marketplace Preconditions -
Main flow The Authenticated user through the dedicated search page makes a request passing the keywords. The system asks the Marketplace for a list of items matching the given keywords and the Marketplace returns the requested list together with all the information the system needs in order to manage the item import. The system shows to the user the list of all the published items that match the given keywords. Secondary flow -
Postconditions The authenticated user can see the search results
VC.UC.4 Import opendata Covered Requirements VC.2.1
Short description The Authenticated user imports an open data in her/his catalogue.
D2.9 – Report on the WeLive Open Service Layer v1 page 77
Actors Authenticated user Open Data Stack Preconditions The selected opendata is not already in the Authenticated user opendata catalogue.
Main flow After a search into the Marketplace, the Authenticated user selects an opendata to be imported. The system asks the ODS for all the information required to use the dataset and the ODS returns the requested information. The system shows to the user that the selected dataset was correctly imported into her/his catalogue. Secondary flow - Postconditions The dataset has been imported in the user opendata catalogue.
VC.UC.5 Import service
Covered Requirements VC.1.1 Short description The Authenticated user imports a service in her/his catalogue.
Actors Authenticated user Preconditions The selected service is not already in the Authenticated user service catalogue.
Main flow After a search into the Marketplace, the Authenticated user selects a service to be imported. The system stores the information about the selected service and shows to the user that the selected dataset was correctly imported into her/his catalogue.
Secondary flow - Postconditions The service has been imported in the user service catalogue.
VC.UC.6 Delete item Covered requirements VC.1.2, VC.2.2
Short description The Authenticated user deletes an imported item (service or opendata) from the Visual Composer. Actors Authenticated user.
Preconditions The Authenticated user is in the Service/Opendata Catalogue page and he is the owner of the selected item.
D2.9 – Report on the WeLive Open Service Layer v1 page 78
Main flow The Authenticated user starts the d elete action. The system performs the action and redirects the user to the catalogue page. Secondary flow -
Postconditions The item has been deleted from the user catalogue.
VC.UC.7 Change item visibility Covered requirements VC.1.1, VC.2.1, VC.3.x
Short description The user makes the selected item (service or opendata) visible to all the members of the workgroup. Actors Modeler.
Preconditions The Authenticated user is in the Service/Opendata Catalogue page and he is the owner of the selected item.
Main flow The user starts the change visibility action. The system performs the action and shows the visibility change. Secondary flow -
Postconditions The item is visible in the catalogue of all the members of the workgroup.
VC.UC.8 Create mashup project Covered requirements VC.4.1
Short description The Modeler creates a new mashup project.
Actors Modeler.
Preconditions The Modeler is the member of at least one workgroup.
Main flow The Modeler requests to create a new mashup project. The system redirects the Modeler to the creation page where the user can specify: Project name (required). Workgroup (required). Description. Tags. Once the Modeler has submitted the form, the system creates the new mashup project. Secondary flow -
D2.9 – Report on the WeLive Open Service Layer v1 page 79
Postconditions The project is available in the Modeler mashup project list and ready to be edited.
VC.UC.9 Create mockup project Covered requirements VC.5.1 Short description The Modeler creates a new mockup project.
Actors Modeler. Preconditions The Modeler is the member of at least one workgroup. At least one mashup project is available to the Modeler. Main flow The Modeler requests to create a new mockup project. The system redirects the user to the creation page where the Modeler can specify: Project name (required). Workgroup (required). Description. Tags. A list of mashup projects. Once the Modeler has submitted the form, the system creates the new mockup project. Secondary flow -
Postconditions The project is available in the Modeler mockup project list and ready to be edited.
VC.UC.10 View project details Covered requirements VC.4.1, VC.5.1
Short description The Modeler accesses the information about the selected project (mashup or mockup). Actors Modeler.
Preconditions The Modeler is a member of the selected project.
Main flow The Modeler requires the details page of the project. The system responds with a page where all the information about the selected project are listed in a user-friendly manner.
Secondary flow - Postconditions The modeler can see the project details
D2.9 – Report on the WeLive Open Service Layer v1 page 80
VC.UC.11 Edit project details
Covered requirements VC.4.1, VC.5.1 Short description The Modeler modifies the information about the selected project (mashup or mockup). Actors Modeler. Preconditions The Modeler is in the project details page and he is the owner of the selected project.
Main flow The Modeler edits the information about the project and submits the form. The system stores the new information and update the details page.
Secondary flow - Postconditions The project details have been updated.
VC.UC.12 Delete project Covered requirements VC.4.1, VC.5.1
Short description The Modeler deletes a project (mashup or mockup) from the Visual Composer. Actors Modeler
Preconditions The Modeler is in the project details page and he is the owner of the selected project. The selected project is not associated with any mockup project.
Main flow The Modeler starts the d elete action. The system performs the action and redirects the Modeler to the list of projects. Secondary flow -
Postconditions The project has been deleted from the system. The projects list has been updated.
VC.UC.13 Add member Covered requirements VC.3, VC.4, VC.5
Short description The Modeler add a member to the selected project (mashup or mockup) so that she/he can collaborate to its realization.
Actors Modeler
D2.9 – Report on the WeLive Open Service Layer v1 page 81
Preconditions The Modeler is in the project details page and he is the owner of the selected project. The new member belongs to the workgroup associated with the project.
Main flow The user selects one or more members to add to the selected project. The system adds the selected members to the project and shows the new list of collaborators.
Secondary flow - Postconditions The member is visible into the project collaborators list. The project has been associated to the member
VC.UC.14 Add comment
Covered requirements VC.3.x, VC.4.x, VC.5.x Short description The Modeler add a comment to the selected project (mashup or mockup) so that project members can read it. Actors Modeler.
Preconditions The Modeler is in the project details page and he is a collaborator of the selected project.
Main flow The user adds a comment to the project. The system notifies the comment to project members and shows it in the project details page.
Secondary flow - Postconditions The comment is visible in the project details page.
VC.UC.15 View projects list Covered requirements VC.4.1, VC.5.1
Short description In the ‘Projects’ section of the Visual Composer the Modeler can find a list of projects (mashup or mockup) visible to her/him (i.e. she/he is the owner or a member). Actors Modeler. Preconditions -
Main flow The Modeler requires the list of projects. The system responds with a page where all the projects visible to the Modeler.
D2.9 – Report on the WeLive Open Service Layer v1 page 82
Secondary flow -
Postconditions The modeler can see the projects list
VC.UC.16 View gadget details Covered requirements VC.5.3 Short description The Modeler accesses the information about the configuration of a mockup project as OpenSocial Gadget Actors Modeler.
Preconditions The Modeler is in the ‘Mockup projects list’ page.
Main flow The Modeler requires the gadget configuration page of the project. The system responds with a page where all the information about the gadget configuration are listed in a user-friendly manner. Secondary flow -
Postconditions The modeler can see the gadget details
VC.UC.17 Configure gadget Covered requirements VC.5.3 Short description The Modeler configures a mockup project in order to export it as OpenSocial Gadget. Actors Modeler.
Preconditions The Modeler is in the ‘OpenSocial gadget’ page of a mockup project.
Main flow The Modeler edits the information about the configuration of the gadget: Title Description Author (name and email) Size (width and height) and submits the form. The system stores the new information and update the page. Secondary flow - Postconditions The gadget configurations have been updated.
VC.UC.18 Export gadget
D2.9 – Report on the WeLive Open Service Layer v1 page 83
Covered requirements VC.5.3
Short description The Modeler exports the mockup project as OpenSocial Gadget.
Actors Modeler.
Preconditions The Modeler is in the ‘OpenSocial gadget’ page of a mockup project. The mockup project is configured as OpenSocial gadget. Main flow The Modeler requires to export the gadget. The system responds with the file representing the gadget.
Secondary flow - Postconditions The gadget has been exported as an Open Social Gadget
VC.UC.19 Export HTML App
Covered requirements VC.5.4 Short description The Modeler exports a mockup projects as HTML Application (HTML, CSS and Javascript).
Actors Modeler. Preconditions The Modeler is in the ‘Mockup projects list’ page.
Main flow The Modeler requires to export the project as HTML Application. The system creates an archive containing all the project file (HTML pages, CSS and Javascript files). The system responds with the archive representing the HTML Application.
Secondary flow - Postconditions The gadget has been exported as a HTML5+CSS web application
VC.UC.20 Publish gadget Covered requirements VC.7.1
Short description The Modeler publishes a mockup project as OpenSocial Gadget into the WeLive Marketplace. Actors Modeler Marketplace Preconditions The Modeler is in the ‘Mockup projects list’ page and she/he is the owner of the selected project. The mockup project is configured as OpenSocial gadget.
D2.9 – Report on the WeLive Open Service Layer v1 page 84
Main flow The Modeler requires to publish the project as OpenSocial gadget. The system responds with the gadget publication page. The Modeler inserts the required publication information: Title Description Category Author (name and email) and submits the form. The system sends these information (together with the gadget file URI) to the Marketplace. The Marketplace gets the gadget file. The Marketplace redirects the user to the Artefact Definition Tool page. Secondary flow -
Postconditions The artefacts has been published in the marketplace
VC.UC.21 Edit mashup project Covered requirements VC.4.2
Short description The Modeler edits a mashup project in order to build a new complex service. Actors Modeler.
Preconditions The Modeler is the owner of the project or one of his/her collaborators.
Main flow The Modeler requests to edit a mashup project. The system gets the list of services/opendata visible to the Modeler and the list of built-in operators. If the project is related to an idea, the system gets the recommended artefacts for that idea (see VC.UC.22). The system redirects the Modeler to the Mashup Editor page. The Modeler builds/edits the logic of the complex service by adding elements from the palette to the working area: Inputs and Output. Services or opendata. Operators. If the user requests to save the project, the system stores the logic of the mashup and then notifies the user. If the user requests to get a preview of the project, the system executes the logic of the mashup and shows the outcome to the user. Secondary flow -
Postconditions The logic implemented by the modeler has been stored.
D2.9 – Report on the WeLive Open Service Layer v1 page 85
VC.UC.22 Get Recommendations
Covered Requirements VC.8 Short description The system gets recommendations about items (services and opendata) useful to implement an idea as a mashup. Actors Decision Engine Marketplace
Preconditions A Modeler has requested to edit a mashup project and the project is associated with an idea form OIA. Main flow The system gets the information about the idea related to the selected project and asks the Decision Engine for items recommended for that idea. The Decision Engine responds to the system with a list of recommended items. The system asks the Marketplace for information about all the items recommended by the Decision Engine. The Marketplace returns the required information. Secondary flow -
Postconditions Recommendations can be seen by the Modeler
VC.UC.23 Edit mockup project Covered requirements VC.5.2 Short description The Modeler edits a mockup project in order to create a new graphical interface for the outcome of mashup projects. Actors Modeler.
Preconditions The Modeler is the owner of the project or one of his/her collaborators. Main flow The Modeler requests to edit a mockup project. The system redirects the Modeler to the Mockup Editor page. The Modeler creates the graphical interface by adding the elements of the palette to the working area. The Modeler can also upload external resources (CSS, Javascript or images) to the project. If the Modeler requests to save the project, the system writes the mockup as HTML Application and then notifies the user. If the Modeler requests to get a preview of the project, the system redirects the user to the main page of the HTML Application.
D2.9 – Report on the WeLive Open Service Layer v1 page 86
If the project is related to an idea, the Modeler can publish a screenshot of the mockup into the Open Innovation Area (see VC.UC.24). Secondary flow -
Postconditions The mockup created by the user has been stored
VC.UC.24 Publish screenshot Covered requirements VC.9
Short description The Modeler makes a screenshot of the current state of the mockup project and publishes it into OIA. Actors Modeler Open Innovation Area Preconditions The Modeler is in the Mockup Editor page. The project is associated with an idea from the OIA.
Main flow The Modeler requests to make a screenshot of the current state of the graphical interface he/she created. The system redirects the user to the screenshot page. The Modeler inserts a short description and makes a screenshot of what is currently shown in the browser. The system sends the screenshot and its description to the OIA. The OIA publishes it into the idea screenshots page. Secondary flow - Postconditions The screenshot is visible in the detail page of the idea in the Open Innovation Area.
VC.UC.25 Create workgroup
Covered requirements VC.3.1 Short description The Administrator creates a workgroup of Modelers.
Actors Administrator Preconditions -
Main flow The Administrator accesses the workgroup creation page from the VC Administration area. The Administrator specifies a name and a description and submits the form. The system stores the new workgroup.
D2.9 – Report on the WeLive Open Service Layer v1 page 87
Secondary flow -
Postconditions The new workgroup has been stored in the system.
VC.UC.26 View workgroup list Covered requirements VC.3.1 Short description The Administrator views the list of existing workgroups.
Actors Administrator Preconditions -
Main flow The Administrator requires the list of workgroups. The system responds with a page where all the existing workgroups are listed. Secondary flow - Postconditions The administrator can see the workgroup list
VC.UC.27 View workgroup details
Covered requirements VC.3.1 Short description The Administrator accesses the information about the selected workgroup.
Actors Administrator Preconditions The Administrator is in the details page of the selected workgroup.
Main flow The Administrator requires the details page of the workgroup. The system responds with a page where all the information about the selected workgroup are listed in a user-friendly manner. Secondary flow - Postconditions The administrator can see the workgroup details
VC.UC.28 Assign modeler to workgroup
Covered requirements VC.3.1 Short description The Administrator assigns one or more modelers to a workgroups.
Actors Administrator
D2.9 – Report on the WeLive Open Service Layer v1 page 88
Preconditions The system has at least one registered modeler. The Administrator created at least one workgroup. The Modeler is not already in the selected workgroup. Main flow The Administrator selects one or more Modelers from the modeler list and starts the add action. The system stores the association between the workgroup and the selected Modelers.
Secondary flow - Postconditions The modelers have been assigned to the workgroup.
VC.UC.29 Edit workgroup
Covered requirements VC.3.1 Short description The Administrator edits the information about a workgroup.
Actors Administrator
Preconditions The Administrator is in the details page of the selected workgroup.
Main flow The Administrator edits the workgroup information and submits the form. The system stores the new information and updates the page. Secondary flow -
Postconditions The workgroup information have been updated.
VC.UC.30 Delete workgroup Covered requirements VC.3.1
Short description The Administrator deletes a workgroup from the Visual Composer.
Actors Administrator Preconditions The Administrator is in the details page of the selected workgroup. The selected workgroup is not associated with any project. The selected workgroup has no members. Main flow The Administrator starts the delete action. The system performs the action and redirects the Administrator to the workgroup list page. Secondary flow - Postconditions The workgroup has been deleted from the system.
D2.9 – Report on the WeLive Open Service Layer v1 page 89
VC.UC.31 Create Idea Workgroup Covered requirements VC.3.2
Short description When an idea in the OIA switches to the implementation phase, OIA asks the Visual Composer to create a workgroup associated with that idea.
Actors Open Innovation Area Preconditions The idea is not already associated with a workgroup
Main flow OIA sends to the VC the information (the list of members and the related idea) about the workgroup to be created. The system creates the workgroup, associates it to the idea and assigns the members to the workgroup. The system creates a new mashup project and a new mockup project both associated with the idea. The system notifies the creation of the workgroup to the OIA. Secondary flow - Postconditions The new workgroup has been stored in the system and associated to the specified OIA idea. Modelers have been assigned to the new workgroup. A new mashup project has been created and related to the idea. A new mockup project has been created and related to the idea.
VC.UC.32 View modelers list Covered requirements VC.10
Short description The Administrator views the list of registered modelers.
Actors Administrator Preconditions -
Main flow The Administrator requires the list of registered modelers. The system responds with a page where all the registered modelers are listed. Secondary flow - Postconditions -
VC.UC.33 View modeler details
D2.9 – Report on the WeLive Open Service Layer v1 page 90
Covered requirements VC.10
Short description The Administrator accesses the information about the selected modeler.
Actors Administrator Preconditions The Administrator is in the ‘Users list’ page of the VC administration area. Main flow The Administrator requires the details page of the user. The system responds with a page where all the information about the selected user are listed in a user-friendly manner. Secondary flow - Postconditions -
VC.UC.34 Enable/Disable modeler Covered requirements VC.10
Short description The Administrator enables/disables the modeler to use the Visual Composer. Actors Administrator
Preconditions The Administrator is in the details’ page of the user.
Main flow The Administrator starts the Enable/Disable action. The system enables/disables the modeler and update the page. Secondary flow -
Postconditions The Modeler is enabled/disabled to use the system
Table 28 - Visual Composer use cases
6.3. DYNAMIC MODEL AND INTEROPERABILITY DEMANDS 6.3.1. SEQUENCE DIAGRAMS The following VC.SD.1 diagram depicts the visualization of the items (service or opendata) catalogue by the Authenticated user . The user, through the browser, requests to the Visual Composer the catalogue and receives a list of all visible items (i.e. items imported by the user and items with Workgroup or Public visibility).
D2.9 – Report on the WeLive Open Service Layer v1 page 91
Figure 28 – Sequence diagram for VC.UC.1 "View items catalogue"
The following VC.SD.2 diagram depicts the visualization of the item details by the Authenticated user . The user, through the browser, selects an element from the catalogue and then she/he is redirected to the details page of the selected item. For a service, the VC shows its name, description and list of operations; for an opendata, the VC shows its name, description and list of resources (i.e. datasets).
D2.9 – Report on the WeLive Open Service Layer v1 page 92
Figure 29 – Sequence diagram for VC.UC.2 "View item details"
The following VC.SD.3 diagram depicts the items searching sequence into the WeLive Marketplace by the Authenticated user . To make simpler searching services or opendata that meet the user’s needs among a possibly very large catalogue, the Visual Composer provides a search bar where the user can put one or more keywords in order to filter the list. Once the user submits the keywords, the Visual Composer shows the list of matching results: for each result, the name, description, rating and image of the item are shown.
D2.9 – Report on the WeLive Open Service Layer v1 page 93
Figure 30 – Sequence diagram for VC.UC.3 "Search items"
The following VC.SD.4 diagram depicts the opendata import sequence. Once the user completes the searching sequence described in Figure 30, she/he can choose an opendata and import it in her/his opendata catalogue.
Figure 31 – Sequence diagram for VC.UC.4 "Import opendata"
D2.9 – Report on the WeLive Open Service Layer v1 page 94
The following VC.SD.5 diagram depicts the service import sequence. Once the user completes the searching sequence described in Figure 30, she/he can choose a service and import it in her/his service catalogue.
Figure 32 – Sequence diagram for VC.UC.5 "Import service"
The following VC.SD.6 diagram depicts the item deletion sequence. Only the owner of the item can delete it.
Figure 33 – Sequence diagram for VC.UC.6 "Delete item"
D2.9 – Report on the WeLive Open Service Layer v1 page 95
The following VC.SD.7 diagram depicts the item change of visibility sequence. In the Visual Composer services and opendata can have three levels of visibility: Private, the item is visible only to its owner; Workgroup, the item is visible to all members of the item owner workgroup; Public, the item is visible to all the users (only the items imported by the Administrator have public visibility). The Modeler who is the owner of the item can switch its visibility from Private to Workgroup and viceversa.
Figure 34 – Sequence diagram for VC.UC.7 "Change item visibility"
The following VC.SD.8 diagram depicts the sequence representing the creation of a new mashup project.
D2.9 – Report on the WeLive Open Service Layer v1 page 96
Figure 35 – Sequence diagram for VC.UC.8 "Create mashup project"
The following VC.SD.9 diagram depicts the sequence representing the creation of a new mockup project.
Figure 36– Sequence diagram for VC.UC.9 "Create mockup project"
The following VC.SD.10 diagram depicts the visualization of the project (mashup or mockup) details by the Modeler.
D2.9 – Report on the WeLive Open Service Layer v1 page 97
Figure 37 – Sequence diagram for VC.UC.10 "View project details"
The following VC.SD.11 diagram depicts the project details editing sequence. Only the owner of the project can edit its details.
D2.9 – Report on the WeLive Open Service Layer v1 page 98
Figure 38 – Sequence diagram for VC.UC.11 "Edit project details"
The following VC.SD.12 diagram depicts the project deletion sequence. Only the owner of the project can delete it. Moreover, a mashup project can’t be deleted if it is associated with a mockup project.
D2.9 – Report on the WeLive Open Service Layer v1 page 99
Figure 39 – Sequence diagram for VC.UC.12 "Delete project"
The following VC.SD.13 diagram depicts the addition of a member to a project. Only the owner of the project can add collaborators to it and only members of the project workgroup can be added as project members.
D2.9 – Report on the WeLive Open Service Layer v1 page 100
Figure 40 – Sequence diagram for VC.UC.13 "Add members"
The following VC.SD.14 diagram depicts the addition of a comment to a project.
Figure 41 – Sequence diagram for VC.UC.14 "Add comment"
D2.9 – Report on the WeLive Open Service Layer v1 page 101
The following VC.SD.15 diagram depicts the visualization of the projects list by the Modeler . The user, through the browser, requests to the Visual Composer the list and receives a list of all visible projects (i.e. projects whose she/he is owner or member).
Figure 42 – Sequence diagram for VC.UC.15 "View projects list"
The following VC.SD.16 diagram depicts the visualization of the gadget details by the Modeler.
Figure 43 – Sequence diagram for VC.UC.16 "View gadget details"
D2.9 – Report on the WeLive Open Service Layer v1 page 102
The following VC.SD.17 diagram depicts the gadget configuration sequence.
Figure 44 – Sequence diagram for VC.UC.17 "Configure gadget"
The following VC.SD.18 diagram depicts the gadget export sequence. If the project is properly configured, the Modeler can export it as OpenSocial gadget and download the relative XML file. This file can be executed in a Gadget Container.
Figure 45 – Sequence diagram for VC.UC.18 "Export gadget"
The following VC.SD.19 diagram depicts the export of a mockup project as HTML Application. Through this sequence, the Modeler can download an archive file containing all the project files (HTML pages, CSS and Javascript files, images). The content of the archive can be deployed in any Web server.
D2.9 – Report on the WeLive Open Service Layer v1 page 103
Figure 46 – Sequence diagram for VC.UC.19 "Export HTML App"
The following VC.SD.20 diagram depicts the publication of an OpenSocial gadget in the WeLive Marketplace. Once published, the gadget is available in the Marketplace Artefacts catalogue and can be installed by any WeLive user into his/her My Page [10].
Figure 47 – Sequence diagram for VC.UC.20 "Publish gadget"
The following VC.SD.21 diagram depicts the mashup editing sequence by the Modeler. The Mashup Editor allows the Modeler to create the mashup logic in a visual way, dragging elements (services, opendata and operators) from the palette, dropping them on the drawing area and linking them each other.
D2.9 – Report on the WeLive Open Service Layer v1 page 104
Figure 48 – Sequence diagram for VC.UC.21 "Edit mashup project"
The following VC.SD.22 diagram depicts the sequence through which the Visual Composer gets recommendations (as suggested services and opendata) from the Decision Engine about the current mashup project. The Modeler can display these recommendations by clicking on the lightbulb on the top-right corner of the Mashup Editor.
D2.9 – Report on the WeLive Open Service Layer v1 page 105
Figure 49 – Sequence diagram for VC.UC.22 "Get recommendations"
The following VC.SD.23 diagram depicts the mockup editing sequence by the Modeler. The Mockup Editor allows the Modeler to build a graphical interface for the outcome of her/his mashup in a visual way, dragging HTML elements from the palette and dropping them on the drawing area.
D2.9 – Report on the WeLive Open Service Layer v1 page 106
Figure 50 – Sequence diagram for VC.UC.23 "Edit mockup project"
The following VC.SD.24 diagram depicts the publication of a mockup screenshot into the WeLive Open Innovation Area. While the Modeler is editing a mockup project, she/he can share the current state of the graphical interface by making a screenshot and then publishing it in the Open Innovation Area, where the screenshot can be voted and commented by the WeLive users.
D2.9 – Report on the WeLive Open Service Layer v1 page 107
Figure 51 – Sequence diagram for VC.UC.24 "Publish screenshot"
The following VC.SD.25 diagram depicts the workgroup creation sequence by the Administration user .
Figure 52 – Sequence diagram for VC.UC.25 "Create workgroup"
The following VC.SD.26 diagram depicts the visualization of the workgroup list by the Administration user .
Figure 53 – Sequence diagram for VC.UC.26 "View workgroup list"
D2.9 – Report on the WeLive Open Service Layer v1 page 108
The following VC.SD.27 diagram depicts the visualization of the workgroup details page by the Administration user .
Figure 54 – Sequence diagram for VC.UC.27 "View workgroup details"
The following VC.SD.28 diagram depicts the assignment of a Modeler to a workgroup by the Administration user .
Figure 55 – Sequence diagram for VC.UC.28 "Assign Modeler to workgroup"
The following VC.SD.29 diagram depicts the workgroup editing sequence by the Administration user .
Figure 56 – Sequence diagram for VC.UC.29 "Edit workgroup"
D2.9 – Report on the WeLive Open Service Layer v1 page 109
The following VC.SD.30 diagram depicts the workgroup deletion sequence by the Administration user .
Figure 57 – Sequence diagram for VC.UC.30 "Delete workgroup"
The following VC.SD.31 diagram depicts the creation of a workgroup related to an idea by the Open Innovation Area .
Figure 58 – Sequence diagram for VC.UC.31 "Create idea workgroup"
The following VC.SD.32 diagram depicts the visualization of the Modelers list by the Administration user .
D2.9 – Report on the WeLive Open Service Layer v1 page 110
Figure 59 – Sequence diagram for VC.UC.32 "View modelers list"
The following VC.SD.33 diagram depicts the visualization of the Modeler details page by the Administration user .
Figure 60 – Sequence diagram for VC.UC.33 "View modeler details"
The following VC.SD.33 diagram depicts the sequence through which the Administration user enables or disables a Modeler to use the Visual Composer.
D2.9 – Report on the WeLive Open Service Layer v1 page 111
Figure 61 – Sequence diagram for VC.UC.34 "Enable/Disable modeler"
6.3.2. INTEROPERABILITY WITH OTHER WELIVE COMPONENTS The VC interacts with many other WeLive components as a provider or consumer of information. The Visual Composer interoperability demands are listed in [1]. Here we report them again and show the related sequence diagrams. VC.INT.1 : The Visual Composer will receive the users list from the Open Innovation Area as the workgroup devoted to implement an idea solution. The following sequence diagram depicts VC.INT.1 interactions.
Figure 62 – VC.INT.1 sequence diagram
The following is the API that makes this interaction possible. Int. demand Id Provider Tool Method Signature VC.INT.1 Visual Composer POST /webservice/ideaworkgroup
D2.9 – Report on the WeLive Open Service Layer v1 page 112
VC.INT.2: The VC will interact with the WeLive Marketplace in order to search and import building blocks and datasets useful to build-up the mashup as the idea solution; The following sequence diagram depicts the VC.INT.2 interactions.
Figure 63 – VC.INT.2 sequence diagram
The following is the API that makes this interaction possible.
Int. demand Id Provider Tool Method Signature VC.INT.2 Marketplace GET /search-artefact-by- keywords/keywords/{keywords}
VC.INT.3: The VC user can export the created solution as an application compliant with Open Social Gadget specifications and publish it in the WeLive Marketplace. The following sequence diagram depicts the VC.INT.3 interactions.
Figure 64 – VC.INT.3 sequence diagram
The VC.INT.3 interoperability demand does not use an API, but is based on a Liferay Action URL that allows the specification of both the server-side action and the redirection page.
D2.9 – Report on the WeLive Open Service Layer v1 page 113
Int. demand Id Provider Tool Method Signature
VC.INT.3 Marketplace GET /wizard-usdl
VC.INT.4: The VC user will benefit from the recommendations coming from the decision engine, in order to identify useful building blocks already published into the marketplace. The following sequence diagram depicts the VC.INT.4 interactions.
Figure 65 – VC.INT.4 sequence diagram
The following are the API that makes this interaction possible.
Int. demand Id Provider Tool Method Signature VC.INT.4 Decision Engine
VC.INT.4 Marketplace GET /get-models-by-id/ids/{artefactsIDs}
VC.INT.5: The VC will interact with the Open Data Stack in order to: 1) obtain all the information it needs to import an Opendata; 2) query a resource. The following sequence diagram depicts the VC.INT.5 interactions.
D2.9 – Report on the WeLive Open Service Layer v1 page 114
Figure 66 – VC.INT.5 sequence diagram
Figure 67 – VC.INT.5 sequence diagram
The following are the API that makes this interaction possible. Int. demand Id Provider Tool Method Signature VC.INT.5 Open Data Stack GET /ods/dataset/{datasetID}
VC.INT.5 Open Data Stack GET /dataset/{datasetID}/resource/{resourceID}/ mapping/info VC.INT.5 Open Data Stack POST /dataset/{datasetID}/resource/{resourceID}/q uery
The following table collects the whole mapping between the VC interoperability demands and the respective APIs provided by VC and by the other WeLive Tools.
D2.9 – Report on the WeLive Open Service Layer v1 page 115
Int. demand Id Provider Tool Method Signature
VC.INT.1 Visual Composer POST /webservice/ideaworkgroup
VC.INT.2 Marketplace GET /search-artefact-by- keywords/keywords/{keywords} VC.INT.3 Marketplace GET /wizard-usdl
VC.INT.4 Decision Engine
VC.INT.4 Marketplace GET /get-models-by-id/ids/{artefactsIDs}
VC.INT.5 Open Data Stack GET /ods/dataset/{datasetID}
VC.INT.5 Open Data Stack GET /dataset/{datasetID}/resource/{resourceID}/ mapping/info
VC.INT.5 Open Data Stack POST /dataset/{datasetID}/resource/{resourceID}/q uery
Table 29 – Mapping between VC interoperability demands and the respective APIs
6.4. TECHNOLOGY CHOICE REASONING AND USAGE DESCRIPTION FOR IMPLEMENTATION Spring 3.2.2 Spring [12] is an open source framework for the development of application under Java platform. It is a valid alternative to the model based on Enterprise JavaBeans (EJB). Compared with the latter, Spring leaves more freedom to developers providing at the same time a wide and well-documented range of simple solutions suitable to the most common problems. Although the basic peculiarities of Spring can be adopted in any Java application, several extensions exist for the developing of web-based application built on the model of the Java EE platform. This issue allowed Spring to gather a lot of consensus and to be recognized among the most important commercial vendor as framework of strategic importance. Hibernate 4 Hibernate [13] is a middleware open source platform for the development of Java application through the use of related framework that provides an Object-relational mapping (ORM) service that is it manages the data persistence on the database by the representation and maintenance on a rational database of a system of Java objects. This software layer is located between the business logic layer and data persistence on the database (Data Access Layer). Hibernate is distributed under LGPL license. Its aim is to provide a Java class mapping in tables of a rational database; basing on this mapping Hibernate manages the storing of objects of such classes on the database. At the same time, it deals with the retrieval of the object from the database, making and performing autonomously the SQL query.
D2.9 – Report on the WeLive Open Service Layer v1 page 116
DBMS PostgreSQL 9.1 PostgreSQL [14] is an object rational data base distributed upon free license (as BSD). PostgreSQL uses the SQL language to perform the query on the data. Those data are stored in tables with foreign keys that act to link correlated data. The programming of PostgreSQL is its strength and main advantage compared with its competitors, i.e. PostgreSQL make easier building application for the real world, using data coming from the data base. PostgreSQL offers:
• Improvement of performance, since the logic is directly applied to the server of the database, reducing the information exchange between client and server; • Improvement of reliability, due to the centralization of control code on the server; • Adding abstracting levels of data directly on the server, the client code can be simpler and pithy jQuery 1.10 jQuery [15] is a Javascript functions library, cross-browser, for developing web application. It aims to simplify the client-side programming of the HTML pages. Through the jQuery it is possible to have several features with few lines of code such as obtaining an element high or disappearing it with fade out effect. In addition, the event management is completely standard and automatic; the same for the usage of AJAX, because there are several useful functionalities that deal with the instantiation of the right objects and performing the connection and sending of data. This framework provide methods and functions to manage graphical and structural aspects such as element position, effect of click on the images, manipulation of the Document Object Model, being compliant among different browser. Draw2D-Touch Draw2D-Touch [16] is a Java Script application framework that aims at creating cross-platform diagram application. It is also cross-browser and works on PC and mobile device basing on jQuery and Raphael libraries. The user interface allows an interactive drawing by using a standard browser. It does not need any further software application or third-parties plug-in and it is compliant with all Web standards. 6.5. ARCHITECTURE AND DEPLOYMENT DIAGRAM The following is the Visual Composer deployment diagram.
Figure 68 – Deployment diagram for Visual Composer
D2.9 – Report on the WeLive Open Service Layer v1 page 117
6.6. DOCUMENTATION AND USER MANUAL 6.6.1. Import Data or Services In the Data & Services section of the Visual Composer, the Authenticated user is able to view the list of visible services ( Service Catalogue ) or opendata ( Opendata Catalogue ). For each element, name, description, visibility and available actions are shown.
Figure 69 – Service catalogue
By clicking on an element in the catalogue, the user is redirected to the Details page of the element. This page shows more information about the selected element, such as a short description or a link to its related page in the WeLive Marketplace, and the list of operations (for services) or resources (for opendata).
Figure 70 – Service details page
If the user wants to add other services or opendata to her/his catalogue, she/he can import them from the WeLive Marketplace. In the Import Artefact page she/he finds a search bar where she/he types some keywords in order to filter the results. When the user clicks on the Search button, the Visual Composer shows the list of artefacts that match the given keywords.
D2.9 – Report on the WeLive Open Service Layer v1 page 118
Figure 71 – Search into WeLive Marketplace
For each artefact, title, description, type (REST, SOAP or Opendata), image and rating are shown. By clicking on the Add to catalogue button, the relative artefact is imported in the user catalogue. If the artefact already exists in the user catalogue, the message ‘Artefact already in catalogue’ is shown. 6.6.2. Create a mashup project In the Projects area of the Visual Composer, the Authenticated user is able to view the list of visible mashup or mockup projects. To create a new project, the Modeler user accesses the Create New Mashup page from the Mashup Projects Management section and then inserts the required information.
Figure 72 – Create a new mashup project
Once created, the new project is visible in the Mashup Projects List page of the user.
D2.9 – Report on the WeLive Open Service Layer v1 page 119
Figure 73 – Mashup projects list
To implement the logic of the mashup, the user clicks on the Edit Mashup button of the selected project and he/she is redirected to the Mashup Editor page.
Figure 74 – Mashup editor and its functional areas
The Mashup Editor has four main functional areas: Toolbar : contains the project control functionalities: o Save : to save the current state of the project o Preview : to get the outcome of the mashup logic (or its sub-part) o Undo, Redo : to un-do or re-do the last operation o Remove element : to remove the selected element from the Working area o Zoom Palette : contains all the elements that can be used to implement the mashup logic Working area : is the area that contains the mashup logic Property panel : displays information about the selected element The Palette is made up by four sections:
D2.9 – Report on the WeLive Open Service Layer v1 page 120
Operation : contains Input and Output elements and all the built-in operators provided by the Visual Composer. An operator is a special mashup element that allows the Modeler to manipulate the outcome of the mashup flow behind it. The operators are grouped by type. Service : contains all the web services (REST and SOAP) visible to the Modeler. Opendata : contains all the opendata visible to the Modeler. Process : contains two kinds of elements: Blackbox , mashup project that can be used as a mashup element in the logic of other projects; Inner process , mashup project whose logic is executed for each element of an array (it can be linked only to an Iterator operator that works with arrays). In order to create the logic of the mashup, the Modeler has to add elements from the Palette to the Working Area . This operation can be simply made by dragging the desired element from the Palette and then dropping it in the Working Area . The following sections will show how to use the different types of element. Service When a service element is dropped on the Working Area , the Visual Composer shows a modal window that allows the Modeler to select one service operation. For each operation, name, category and documentation are shown.
Figure 75 – Modal window that shows the service operations
When the Modeler selects the operation, the element representing the web service will appear in the Working Area and then it can be linked to other elements. In order to use a service element, the Modeler has to bind its input parameters to one or more elements of the Working Area . To do that, the user clicks on the right end of a source element and then traces a line to the left end of the service element.
D2.9 – Report on the WeLive Open Service Layer v1 page 121
Figure 76 – How to link the output of a source element to the input of a target element
Then the Visual Composer shows a new modal window that displays, on the left side, the tree representing the source element outcome, and on the right side, all the input parameters required by the service in order to be invoked. So the Modeler selects which input parameter bind to the source element by simply dragging the input object from the left side of the modal to the desired parameter position.
Figure 77 – How to bind an input object to an input parameter of a service element
Once the Modeler binds all the input parameters to one or more source elements, the service element will be ready to be used as source element or to be linked to the Output element. If the user selects a service element from the Working Area , the Property Panel will show information about the selected service including the current values of its input parameters.
D2.9 – Report on the WeLive Open Service Layer v1 page 122
Figure 78 – Property panel of the selected service element
Opendata When an opendata element is dropped on the Working Area , the Visual Composer shows a modal window that allows the Modeler to select which resource to use. For each resource, name, description and dataset schema are shown.
Figure 79 – Modal window that shows the opendata resources
Once the user selects a resource, the Visual Composer will show a modal window containing the Query Editor . The Query Editor is a VC component that supports the Modeler to build a SQL query. It consists of five sections: SQL query: contains the current text of the query SELECT: allows the user to select which fields of the dataset to include in the query results
D2.9 – Report on the WeLive Open Service Layer v1 page 123
WHERE: allows the user to specify conditions (rules) on which the query results will be filtered ORDER BY: allows the user to select which field the query results will be ordered by LIMIT: allows the user to specify the maximum number of rows in the query results
Figure 80 – Query Editor
When the Modeler finishes to edit the query, the element representing the opendata will appear in the Working Area and then it can be used as source for other elements (an opendata element has no inputs). Operators The Visual composer provides a large set of built-in operators and each of them has a specific behavior. The list of operators is shown in the following table.
Name Description Category Input parameters Output Key/Value Pair Returns an array containing Object Object Array List the key/value pairs of the input object Comparator Applies the specified Object Object Object conditions to key/value pairs Conditions (N) {“result”: of the input object and true/false} returns true or false Filter Object Returns a new object Object Object Object containing only the selected Options (N) fields of the input object Iterator Applies the logic of an inner Array Array Array process to each element of Inner process an array and returns the concatenation of results Get Element Returns the element of the Array Array Object array at the given index Object field: integer
D2.9 – Report on the WeLive Open Service Layer v1 page 124
Filter Applies the specified Array Array Array conditions to key/value pairs Conditions (N) of each element of the input array and returns only the elements that match the conditions Join Joins two arrays on the Array Arrays (2) Array specified fileds Text: string (2) Slice Returns the elements of the Array Array Array input array between the Text: integer (2) specified indexes Pluck Returns the input array but Array Array Array its elements contain only the Options (N) selected fields Sort By Returns the input array Array Array Array sorted by the specified field Option (2) Unique Removes elements with Array Array Array duplicate values of the Option specified field Group By Groups the elements of the Array Array Array input array by the selected Option field value Count Returns the length of the Array Array Object input array {“length”: integer} Property Rename For each element of the Array Array Array input array renames the Text: string selected field with the specified name Split Splits the input string on the String Object field: string Array given delimiter Text: string (2)
Replace Applies the specified regular String Object field: string Object expression to the input string Text: string (2) {replaced string} and replaces the matches Option with the specified string String Concat Concatenates two strings; it String Object field: string is possible to specify a (2) separator between the Text: string source strings Fuse Receives N objects and Mashup Objects (N) Object returns a new object containing all the fields in the input objects.
D2.9 – Report on the WeLive Open Service Layer v1 page 125
Fuse Array Receives N arrays of the Mashup Arrays (N) Array same size in input and returns a new array whose elements contain all the fields of the input elements. Objects Concat Returns an array whose Mashup Objects (N) Array elements are the input objects. Arrays Concat Concatenates two or more Mashup Arrays (N) Array arrays. JSON Maker Creates a new object with Mashup Text: string (N) Object the specified key/value pairs Any (N)
Branch Evaluates the condition given Mashup Object field: Object or Array in input and returns the true/false second input if the condition Any (2) is true or the third if not Add Object To Adds the input object (as Mashup Array Array Array new field) to every element Object of the input array Formula Creates a formula by adding Utility Object field: number Object operands and operators (+,- (N) {“result”: ,*,/) and evaluates it. Operands (N) number} Value Matcher Check if two input values are Utility Object field: any (2) the same or not. XML Converter Converts the XML input to Utility Object field: string Object object (JSON) JSON Converter Converts a string Utility Object field: string Object representing JSON to object (JSON) Invoker Receives the endpoint of a Utility Object field: string Any REST web service and an Option (2) object containing its inputs Object and then calls the service. Table 30 – Complete list of the built-in mashup operators
When an operator is linked to another element of the Working Area , the Visual Composer shows a modal window that displays, on the left side, the tree representing the source element outcome, and on the right side, all the input parameters required by the operator. Therefore, the Modeler selects which input parameter bind to the source element by simply dragging the input object from the left side of the modal to the desired parameter position. Some input parameters do not require any input object and can be typed by the user.
D2.9 – Report on the WeLive Open Service Layer v1 page 126
Figure 81 – How to set the input parameters of operators
Once the Modeler completes the mashup logic, she/he can save the project and get a preview of the mashup outcome using the control buttons in the Toolbar .
Figure 82 – Mashup example
When the user clicks on the Preview button, the Visual Composer executes the mashup logic and displays its outcome as a tree in a new modal window.
D2.9 – Report on the WeLive Open Service Layer v1 page 127
Figure 83 – Mashup outcome
6.6.3. Create a mockup project To create a new mockup project, the Modeler user accesses the Create New Mockup page from the Mockup Projects Management section and then inserts the required information. A mockup project can be associated with more than one mashup project of the same workgroup.
Figure 84 – Create a new mockup project
Once created, the new project is visible in the Mockup Projects List page of the user.
D2.9 – Report on the WeLive Open Service Layer v1 page 128
Figure 85 – Mockup projects list
To create the mockup, the user clicks on the Edit Mockup button of the selected project and he/she is redirected to the Mockup Editor page.
Figure 86 – Mockup editor and its functional areas
The Mockup Editor has four main functional areas: Toolbar: contains the project control functionalities: Save : to save the current state of the project Preview : to get a preview of the mockup Remove element : to remove the selected element from the Working area Clear : to clear the Working Area Project files : to add or manage the files of the projects (CSS, Javascript and images) New page : to add a new Html page to the project Mockup configuration : to configure the Html project as a Single Page Application Palette : contains all the elements that can be used to create the mockup, grouped by category (containers, lists, forms etc.)
D2.9 – Report on the WeLive Open Service Layer v1 page 129
Working area: is the area that contains the graphical user interface Property panel: displays properties of the selected element. The first group of properties allows to configure the special behaviour of the selected element; the other groups of properties define the layout and the style of the element. In order to create a graphical interface, the Modeler has to add elements from the palette to the Working Area . This operation can be simply made by dragging the element from the Palette and then dropping it on the Working Area in the desired position. The following sections will show how to use the different types of element. Form The form is the main element of the Mockup Editor palette because it allows to invoke one or more mashups associated with the current mockup project. To configure a form in order to invoke a mashup, the Modeler has to: Select the form in the Working Area ; the Visual Composer will show the special properties of the form in the Property Panel on the right side of the Mockup Editor ; Populate the Action section of the Properties by clicking on the button on its right; Select at least one mashup from the mashup list. The selected mashups will be invoked when the form is submitted.
Figure 87 – How to configure a form
Once the form is configured, the Modeler has to bind form inputs to the mashup ones. So she/he selects an input element inside the form and then she/he clicks on the bind button on the right of the name property.
D2.9 – Report on the WeLive Open Service Layer v1 page 130
Figure 88 – How to configure a form input
The Visual Composer opens a modal window where the inputs of all the mashup project associated with the current mockup are listed. Therefore, the Modeler selects one of the inputs on the list and clicks Ok . That input is now bound to the selected form input and its id will appear under the name property of the form input.
Figure 89 – Modal window that shows the list of mashups inputs
This process must be repeated for each input of the mashup/s to be invoked by the form. To add a new input to the form, the Modeler drags the Form Input Text element (or the Input Text element) from the Palette to the form area in the Working Area . As the Modeler holds the element on the Working Area , the Visual Composer lights the position where the element will be rendered once dropped.
D2.9 – Report on the WeLive Open Service Layer v1 page 131
Figure 90 – How to add a new input to the form
Usage Example: Table The table allows the Modeler to easily display the outcome of a mashup that returns a list of results (array). To configure a table, the Modeler has to: 1. Select the table in the Working Area ; the Visual Composer will show the special properties of the table in the Property Panel on the right side of the Mockup Editor; 2. Click on the Select Body button and then click on the foreach button: the Visual Composer will show a modal window where the inputs of all the mashup associated with the current mockup project are listed; 3. Populate the list of inputs and click Ok : the Visual Composer will invoke all the mashup associated with the current mockup project and show their outcomes in a new modal window; 4. Select an array from the results tree and click Ok . The table is now bound with the elements of the selected array.
D2.9 – Report on the WeLive Open Service Layer v1 page 132
Figure 91 – How to configure a table
Figure 92 – Insert parameters to invoke mashups
D2.9 – Report on the WeLive Open Service Layer v1 page 133
Figure 93 – Select the array to bind with the table
Now the Modeler has to select which fields of the mashup outcome she/he wants to display in the table columns. To add a field, she/he has to: 1. Add a span element to the desired column of the table, in the cell area; 2. Select the span element in the Working Area and click on the text button in the Property Panel: the Visual Composer will show again the modal window in Figure 93; 3. Populate the list of inputs and click Ok : this time the Visual Composer will invoke only the mashup whose outcome is bound with the table and show the content of a single element of the array selected during the table configuration; 4. Select the field to display in the span and click Ok .
Figure 94 – Table and its functional areas
D2.9 – Report on the WeLive Open Service Layer v1 page 134
Figure 95 – How to configure a span element
Figure 96 – Binding of a field with a span element
This process must be repeated for each field (of the array element) that the Modeler wants to display in the table. More columns can be added to the table by simply selecting the table in the Working Area and then clicking on the Add Column button in the Property Panel . Once the Modeler completes the graphical interface, she/he can save the project and get a preview of the mockup outcome using the control buttons in the Toolbar .
D2.9 – Report on the WeLive Open Service Layer v1 page 135
Figure 97 – Mockup preview example
6.7. DATA PROTECTION RELATED REQUIREMENTS FOR VC
Requirement Related questions VC component
In a system like WeLive there is Are the consent During the pilots the users will sign a printed the requirement for the consent of form processes consent form that will provide inform them about the individuals concerned. included in the the usage of their personal data and the rights system design? they have when using the platform. If a youngster of below 16 years Who is designing As the consent forms are aimed for users providing wishes to use online services, the the consent form personal information that is collected by the service provider has to try to and the terms of system, they are shown the first time the user verify that parental consent has use for various user creates a new account. been given. groups? According to the registration scenario described in In addition the controller shall be WeLive-WP2-D213, during the registration, the able to demonstrate that consent Sign up page provides the consent form and after was given by the data subject to the registration phase, the consent settings can be the processing of their personal shown and changed through a consent form data. provided by the CDV and the AAC. The consent form is designed by Laurea and translated to other required languages by project partners. It is impossible to verify the parental consent into
D2.9 – Report on the WeLive Open Service Layer v1 page 136
the WeLive Platform, because it does not support the parental relationship among users.
The system has to provide easy How are these The VC provides the functionalities to allow each access to your own data, including requirements to be user to see its profile data and to see the how their data is processed. This taken into account catalogue of the projects it is involved. information should be available in in the system design In order to allow the information portability, the a clear and understandable way. and in various VC will provide a functionality to export personal building blocks and profile data in textual format (JSON). Further there is a right to applications? portability, facilitating the According to the “ right to be forgotten ”, the VC transmission of personal data will exposes an API invoked by the CDV in order to from one service provider. delete the user account from the users database. The technical details about user removal have still Individuals have also a right to to be agreed. erase personal data and "to be In order to ensure the database integrity, the forgotten". This enables subjects projects owned by the deleted user will be to require the removal, without maintained and related to a ”deleted user”. delay, of personal data collected or published. Individuals have the right to know How are the system Authenticated user, the only ones that can store when your data has been hacked: and its various personal information inside the system, need to Companies and organisations components to be provide a valid e-mail account during the must notify the national monitored from this registration process. supervisory authority of serious viewpoint? This account will be used by the Visual Composer data breaches as soon as possible Administrator for notification purposes, in the in so that users can take appropriate the event of some data breach that can measures. compromise their personal data stored in the system.
Individuals have the right to How is this feature The consent form will inform the user that the object to the processing of to be taken into data will be gathered for scientific and statistical personal data relating to the account in the purposes and to enable a customized experience public interest or to legitimate system (citizen data using the WeLive Tools, the Public Service interests of a controller. This right vault, decision Applications and the Building Blocks. covers the use of personal date engine and for the purposes of 'profiling'. analytics)?
(Common safeguards covering the processing of personal data for archiving purposes where that is in the public interest and for scientific and historical research or statistical purposes.) Transfer of personal data outside This is to be taken The VC will be deployed during the pilots in a the EU: the regulation lays down when figuring out server located inside the EU. Therefore, will be
D2.9 – Report on the WeLive Open Service Layer v1 page 137
the rules for transferring personal the business model applied the European Union regulations. data to third countries and and the hosting international organizations. environments. Transfer may take place provided that a number of conditions and safeguards are met. The Act is based on “risk-based How is the overall Privacy issues have been an integral part of the VC approach”: the stronger the risks security design process. of the activities for the personal architecture of the According to the ”Privacy by default” principles, data, the more stringent the WeLive? How Is the the VC stores only the user information required obligations are. Processing privacy by design- to the identification (Login/Logout operation), and sensitive data (including race, approach applied? does not expose APIs to provide user information. health) is of a special concern. (see also deliverable According to the ”Privacy by design” principles, Requirements include Privacy 5.3) the user is able to access only to the project where Impact Assessment and other the it has been involved. measures needed to tackle risks.
Data protection safeguards are to be built into products and services from the earliest stage of development (Data protection by design and default). Such measures could consist inter alia of minimizing the processing of personal data, pseudonymising personal data a.s.a.p, transparency with regard to the functions and processing of personal data, enabling the data subject to monitor the data processing, enabling the controller to create and improve security features. Any processing of personal data in This is to be taken The VC is responsible only of the maintenance of the context of the activities of an when figuring out the user generated content (projects and gadgets), establishment of a controller or a the business model but does not process/elaborate this information. processor is to be carried out in and the hosting accordance with regulation, environments. regardless of whether the processing itself takes place within the Union or not. Responsibilities between controller of the data and the processor of the data have to be defined clearly. Table 31 – Visual Composer ethical and data protection requirements
D2.9 – Report on the WeLive Open Service Layer v1 page 138
6.8. FUNCTIONAL TESTS RESULTS OF THE VISUAL COMPOSER The following table shows the results of the functional tests performed against the use cases described in section 6.2.3:
Test ID Name Mapped Date Tests results (Iteration #1) Date Tests results (Iteration #2) use cases (Iteration #1) (Iteration #2) (PASSED/PASSED WITH (PASSED/PASSED WITH RESERVE/NOT PASSED) RESERVE/NOT PASSED)
VC.FT.1 View items catalogue VC.UC.1 13/04/2016 PASSED WITH RESERVE: OK for 18/04/2016 PASSED service; Not tested for open data as item can’t be imported
VC.FT.2 View item details VC.UC.2 13/04/2016 PASSED WITH RESERVE: title of the 18/04/2016 PASSED selected service details page is “Open Data details”; Not tested for open data as item can’t be imported
VC.FT.3 Search items VC.UC.3 13/04/2016 PASSED 18/04/2016 PASSED
VC.FT.4 Import opendata VC.UC.4 13/04/2016 NOT PASSED: when open data item 18/04/2016 PASSED is selected for import the message “Artefact is not a valid service or opendata” is presented and item is not imported
VC.FT.5 Import service VC.UC.5 13/04/2016 PASSED WITH RESERVE: : when REST 18/04/2016 PASSED item is selected for import the message “Artefact is not a valid service or opendata” is presented, but item is imported; Also, it is possible to import the item already imported
VC.FT.6 Delete item VC.UC.6 13/04/2016 PASSED WITH RESERVE: OK for 18/04/2016 PASSED
D2.9 – Report on the WeLive Open Service Layer v1 page 139
service; Not tested for Open data as item can’t be imported
VC.FT.7 Change item visibility VC.UC.7 13/04/2016 PASSED 18/04/2016 PASSED
VC.FT.8 Create mashup project VC.UC.8 13/04/2016 PASSED 18/04/2016 PASSED
VC.FT.9 Create mockup project VC.UC.9 13/04/2016 PASSED WITH RESERVE: title of the 18/04/2016 PASSED create page is “Create new Mashup”
VC.FT.10 View project details VC.UC.10 13/04/2016 PASSED 18/04/2016 PASSED
VC.FT.11 Edit project details VC.UC.11 13/04/2016 PASSED
VC.FT.12 Delete project VC.UC.12 13/04/2016 PASSED
VC.FT.13 Add member VC.UC.13 13/04/2016 PASSED
VC.FT.14 Add comment VC.UC.14 13/04/2016 PASSED
VC.FT.15 View project list VC.UC.15 13/04/2016 PASSED
VC.FT.16 View gadget details VC.UC.16 14/04/2016 PASSED
VC.FT.17 Configure gadget VC.UC.17 14/04/2016 PASSED
VC.FT.18 Export gadget VC.UC.18 14/04/2016 PASSED
VC.FT.19 Export HTML App VC.UC.19 14/04/2016 PASSED
VC.FT.20 Publish gadget VC.UC.20 14/04/2016 PASSED
VC.FT.21 Edit mashup project VC.UC.21 14/04/2016 PASSED WITH RESERVE: OK but not 18/04/2016 PASSED WITH RESERVE: OK but not tested for all options tested for all options from palette
VC.FT.22 Get Recommendations VC.UC.22 18/04/2016 NOT PASSED: DE not yet integrated with VC
D2.9 – Report on the WeLive Open Service Layer v1 page 140
VC.FT.23 Edit mockup project VC.UC.23 14/04/2016 PASSED WITH RESERVE: OK for 18/04/2016 PASSED WITH RESERVE: OK but not service; Not tested for Open data as tested for all options from palette item can’t be imported
VC.FT.24 Publish screenshot VC.UC.24 18/04/2016 PASSED WITH RESERVE: Screenshot is published from VC, but not shown in OIA
VC.FT.25 Create workgroup VC.UC.25 Admin access needed 18/04/2016 PASSED
VC.FT.26 View workgroup list VC.UC.26 Admin access needed 18/04/2016 PASSED
VC.FT.27 View workgroup VC.UC.27 Admin access needed 18/04/2016 PASSED details
VC.FT.28 Assign modeler to VC.UC.28 Admin access needed 18/04/2016 PASSED workgroup
VC.FT.29 Edit workgroup VC.UC.29 Admin access needed 18/04/2016 PASSED
VC.FT.30 Delete workgroup VC.UC.30 Admin access needed 18/04/2016 PASSED
VC.FT.31 Create Idea VC.UC.31 18/04/2016 PASSED Workgroup
VC.FT.32 View modelers list VC.UC.32 Admin access needed 18/04/2016 PASSED
VC.FT.33 View modeller details VC.UC.33 Admin access needed 18/04/2016 PASSED
VC.FT.34 Enable/Disable VC.UC.34 Admin access needed 18/04/2016 PASSED modeller
Table 32 - Visual Composer functional tests
D2.9 – Report on the WeLive Open Service Layer v1 page 141
The Visual composer is the main WeLive tool that will be used in pilots phase II. As the tailoring of the Visual composer is in progress, three tests passed with reserve and one test did not pass. In particular: VC.FT.21 and VC.FT.23 actually passed but detailed tests of all operators from the pallet will be done before the beginning of pilots phase II when most of building blocks provided by cities will be published into the marketplace; VC.FT.22 not passed as the final integration of the DE with the Visual Composer is in progress. The integration will be finished when the second phase of pilots phase I will start; VC.FT.24 passed with reserve as the integration between the Visual Composer and the Open Innovation Area is almost finished but some software tests have to be performed yet.
D2.9 – Report on the WeLive Open Service Layer v1 page 142
7. WELIVE PLAYER SPECIFICATIONS 7.1. FUNCTIONAL ASPECTS OF THE WELIVE PLAYER WeLive Player provides the user with the possibility to access the city service ecosystem through a mobile application (WeLive Player app). More specifically, the functionality of the app enables the search and discovery of the public service applications of the city, taking into account the user context, profile, and preferences. To accomplish this goal, the WeLive Player app relies on a set of WeLive tools: WeLive Marketplace: to search for and obtain the list of the applications given the specific criteria (geographical references, app types and domains); WeLive Decision Engine: to obtain service recommendations based on the user preferences and profile; WeLive CDV: to obtain and manage the user preferences that drive the search and service recommendations; WeLive AAC: to authenticate the user and enable the access to the protected resources on her behalf. Structurally, WeLive Player consists of two parts: the mobile app and the WeLive Player REST API backend. In this way, the mobile app exposes the relevant functionality directly to the end users, while the backend integrates the information from different WeLive components into a single protected API, aggregating, caching, and transforming the relevant data into a suitable format. 7.2. DETAILED REQUIREMENTS AND USE CASE MODEL 7.2.1. DETAILED REQUIREMENTS The following table summarizes the macro-requirements elicitation of the WeLive Player included in [1].
ID Name Description
WLP.1 Support discovery and The users shall be able to discover and access the execution of city services available in the city service ecosystem services through player thorough a mobile app named WeLive Player. The app services proposed to the users shall be selected according to his/her context (e.g., city and profile), needs and preferences. Suitable search, filtering and ordering functionalities shall be provided to facilitate the discovery of services. Selected apps can be installed on the device from the Player. This is a coarse-grained requirement, which acts as container for requirements WLP.2-4.
WLP.2 Management of user The WeLive Player application shall offer the preferences possibility to users to define, store and modify preferences; these preferences shall be used by the Player to facilitate the discovery and recommendation of useful services. User preferences should actually be stored in the CDV, which should be the unique place where such
D2.9 – Report on the WeLive Open Service Layer v1 page 143
preferences are available.
WLP.3 Access to user profile The WeLive Player application shall be able to stored in the CDV access the user profile stored in the CDV; the obtained from the CDV profile shall be used by the Player to facilitate the discovery and recommendation of useful services.
WLP.4 Recommendation of The WeLive Player application shall be able to services suggest and recommend to the user apps and services that may be of interest and that my address user wants and needs. The recommendation shall be based both on user preferences and profile information (see WLP.1 and WLP.2) and on matchmaking mechanisms offered by the Decision Engine.
Table 33 – Macro-requirements elicitation of the WeLive Player included in [1] In tables below, the detailed requirements are reported.
ID WLP.1.1
Name Application Search
Requirement Type Functional
Description The user shall be able to search for the public service applications, using the WeLive Player app. The search should take into considerations different criteria including Geographical information reference Application rating Relevance to the user profile and preferences (interest, context) Search filters and ordering.
Rationale WeLive aims at providing a set of tools to enable to maximize interaction of city stakeholders with the publicly available services. The WeLive Player is one of these tools and acts as a broker between the WeLive-enabled public service ecosystem and the needs and wants of the users of these services.
Fit Criterion Availability of the WeLive Player mobile app on the app repository. The app should (Measurable) cover the 4 pilot cities / regions involved in the WeLive project. This app should be based on HTML5 so that both a web and mobile app (hybrid app in reality) version
of the apps are made available.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the availability of a (Attainable) repository to search, and download the apps. It also depends on the
D2.9 – Report on the WeLive Open Service Layer v1 page 144
accomplishment of the requirements associated to the CDV.
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors App developers shall register apps and services so that they are accessible from the WeLive Player. Citizens shall exploit the functionality of browsing through the available services to identify apps they are interested in.
Author FBK team.
Revision V1.0, 29/02/2016
ID WLP.1.2
Name Application Download and Installation
Requirement Type Functional
Description The user shall be able download and install the application directly from the WeLive player app.
Rationale The WeLive Player enables the citizens to directly interact with the city applications that meet the needs and wants of the users of these services.
Fit Criterion Availability of the WeLive Player mobile app on the app repository. The app should (Measurable) cover the 4 pilot cities / regions involved in the WeLive project.
Priority 5 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the availability of a (Attainable) repository to search, and download the apps.
Difficulty 3 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors App developers shall register the apps together with their access information so that they are accessible from the WeLive Player. This information is exploited by the citizen do download and install the app.
Author FBK team.
Revision V1.0, 29/02/2016
ID WLP.2
Name Management of user preferences
Requirement Type Functional
D2.9 – Report on the WeLive Open Service Layer v1 page 145
Description The WeLive Player application shall offer the possibility to users to define, store and modify preferences; these preferences shall be used by the Player to facilitate the discovery and recommendation of useful services. User preferences should actually be stored in the CDV, which should be the unique place where such preferences are available.
Rationale Users shall be offered the possibility to find services and apps fulfilling their needs and wants. The possibility for users to explicitly expressed preferences according to their interests, needs and wants – and to optimize the behaviour of the app according to these preferences – contributes to the achievement of this goal.
Fit Criterion The WeLive Player app offers the possibility to the user to define and modify the (Measurable) information about his/her preferences. The preferences shall be stored across usage sessions of the app. The preferences are exploited in the app filtering and
ordering functionalities offered by the Player.
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts The following requirements are blocked by this one: WLP.1.1
Constraints The accomplishment of this requirement critically depends on the availability of (Attainable) information associated to the WeLive apps and services in the repository that can be used to match the apps against the user preferences in the CDV. (See Marketplace and CDV requirements). This requirement is complementary to WLP.1.1. This requirement encompasses WLP.3, it is blocked by it.
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors App developers shall associate information to the apps they publish in the Marketplace that can be matched against the user preferences stored in the CDV. WeLive Framework shall automatically extract information to be associated to the apps that can be matched against user preferences. Citizens shall define user preferences to customize and optimize the behaviour of the Player.
Author FBK team.
Revision V1.0, 29/02/2016
ID WLP.3
Name Access to user profile stored in the CDV
Requirement Type Functional
Description The WeLive Player application shall be able to access the user profile stored in the CDV; the obtained from the CDV profile shall be used by the Player to facilitate the discovery and recommendation of useful services.
Rationale The CDV is a core component of the WeLive Framework, as it allows for a cross- component management of user profiles. It is hence important to exploit this information to optimize the discovery and recommendation functionalities of the
D2.9 – Report on the WeLive Open Service Layer v1 page 146
Player (see WPL.1.1).
Fit Criterion The WeLive Player app is able to access the user profile stored in the CDV. The (Measurable) profile is exploited in the app filtering and ordering functionalities offered by the Player (see WLP.1).
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts The following requirements are blocked by this one: WLP.2.
Constraints The accomplishment of this requirement critically depends on the accessibility of (Attainable) the CDV profile of the user from the Player. This includes finding a suitable solution for access control. It also requires identifying a shared model for the profile information in the CDV. This requirement contributes to WLP.1.1, WLP.2 and WLP.3.
Difficulty 4 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors WeLive Framework shall allow the Player access to the user profile stored in the CDV. WeLive framework components shall contribute to enrich and update the user profile in the CDV.
Author FBK team.
Revision V1.0, 29/02/2016
ID WLP.4
Name Access to user profile stored in the CDV
Requirement Type Functional
Description The WeLive Player application shall be able to access the user profile stored in the CDV; the obtained from the CDV profile shall be used by the Player to facilitate the discovery and recommendation of useful services.
Rationale The CDV is a core component of the WeLive Framework, as it allows for a cross- component management of user profiles. It is hence important to exploit this information to optimize the discovery and recommendation functionalities of the Player (see WPL.1.1).
Fit Criterion The WeLive Player app is able to access the user profile stored in the CDV. The (Measurable) profile is exploited in the app filtering and ordering functionalities offered by the Player (see WLP.1).
Priority 4 (Scale from 1=low priority to 5=highest priority).
Conflicts The following requirements are blocked by this one: WLP.2.
D2.9 – Report on the WeLive Open Service Layer v1 page 147
Constraints The accomplishment of this requirement critically depends on the accessibility of (Attainable) the CDV profile of the user from the Player. This includes finding a suitable solution for access control. It also requires identifying a shared model for the profile information in the CDV. This requirement contributes to WLP.1.1, WLP.2 and WLP.3.
Difficulty 4 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors WeLive Framework shall allow the Player access to the user profile stored in the CDV. WeLive framework components shall contribute to enrich and update the user profile in the CDV.
Author FBK team.
Revision V1.0, 29/02/2016
Table 34 – WeLive Player detailed requirements
7.2.2. USE CASE MODELS The WeLive Player app involves in its uses cases the authentication. The authentication of the citizen takes place directly in the WeLive Player app using the functionality exposed by the AAC building block. The following diagram illustrates the WeLive Player use cases.
Figure 98 – WeLive Player use case diagram
WLP.UC.1 Search apps Covered requirements WLP.1.1, WLP.3, WLP.4
Short description The WLP provides the interface to list, order, and filter the apps, given the user profile and preferences.
Actors Authenticated user. Preconditions -
Main flow The user operates the list of apps through the set of filters including city, text search, ordering. The app presents the list of the
D2.9 – Report on the WeLive Open Service Layer v1 page 148
corresponding PSAs.
Secondary flow - Postconditions The authenticated user can see the apps
WLP.UC.2 View app details Covered requirements WLP.1.1
Short description The WLP provides the interface to view app details including the rating and user comments.
Actors Authenticated user. Preconditions -
Main flow The user accesses the information about individual app.
Secondary flow - Postconditions The authenticated user can see the app details
WLP.UC.3 Change preferences Covered requirements WLP.2, WLP.3
Short description The WLP provides the interface to view and modify the user preferences
Actors Authenticated user. Preconditions -
Main flow The user accesses the information about its profile. The app presents the form with the possibility to modify the preferences information. Secondary flow -
Postconditions The authenticated user can see her profile
WLP.UC.4 Recommend apps Covered requirements WLP.4
Short description The WLP proactively recommends the user the relevant apps given her profile.
Actors Authenticated user.
D2.9 – Report on the WeLive Open Service Layer v1 page 149
Preconditions -
Main flow The WeLive Player informs the user about the existence of new apps that may of interest. Secondary flow -
Postconditions The authenticated user can get app recommendations.
WLP.UC.5 Download app Covered requirements WLP.1.2
Short description The WLP provides the way to download the app.
Actors Authenticated user.
Preconditions Application is not yet installed on the mobile device. The app is publicly available for download. Main flow The user accesses the information about the app. The app presents the download link if the app has not yet been installed. Secondary flow -
Postconditions The authenticated user can download the app
Table 35 – WeLive Player use cases
7.3. DYNAMIC MODEL AND INTEROPERABILITY DEMANDS The following sequence diagram represents the interaction of the user with the WeLive Player app in order to retrieve and update the user profile and preferences using the CDV component ( WP.INT.2 interaction in [1]). The user retrieves the profile from the app. The profile is obtained from the CDV and stored locally for future uses.
D2.9 – Report on the WeLive Open Service Layer v1 page 150
Figure 99 – WLP Profile view and update sequence diagram
The following sequence diagram represents the interaction of the authenticated user with the WeLive Player app in order to view the apps, using different search criteria and filters. The resulting list is obtained out of matching apps obtained from the service marketplace repository ( WP.INT.1 interaction from [1]). The results are combined with the results of the service recommendations obtained from the Decision Engine component (WP.INT.3 interaction in [1]).
D2.9 – Report on the WeLive Open Service Layer v1 page 151
Figure 100 – WLP Sequence Diagram for the app search
The interactions of the use cases WLP.UC.2 (view app details) and WLP.UC.5 (download app) are straightforward. 7.4. TECHNOLOGY CHOICE REASONING AND USAGE DESCRIPTION FOR IMPLEMENTATION 7.4.1. WLP Mobile App The WeLive Player mobile application is implemented as a hybrid mobile app using the Apache Cordova [17] and Ionic [18]frameworks. In this way, the app may be delivered and distributed as a mobile app through the corresponding App markets on different platforms (Android, iOS, etc). as a Web application integrated in the portal. Apache Cordova The Cordova framework is an open source platform for creating the mobile applications for different operation systems, using the Web technologies, namely HTML and JavaScript. It allows embedding of the native platform functionality (sensors, database, etc.) through the plugin mechanism. The framework supports the delivery of the application to a wide range of operation systems. Ionic Framework Ionic Framework is an open source set of instruments and libraries of mobile-optimized HTML, CSS and JS CSS components, gestures, and tools for building highly interactive mobile apps on top of the Apache Cordova. Built with Sass and optimized for AngularJS, state of art technologies for building HTML5 and JavaScript-based solutions. 7.4.2. WLP Server The server-side application relies on the information obtained from the other WeLive components, namely Marketplace service repository, the CDV, and the Decision Engine. No persistent layer is foreseen in this implementation; for efficiency, the data obtained from the Marketplace is cached using simple in-memory caching mechanisms. The server app is implemented as a Java Web application using the Spring Framework [12].
D2.9 – Report on the WeLive Open Service Layer v1 page 152
7.5. DOCUMENTATION AND USER MANUAL 7.5.1. Installation The WLP server app may be deployed to any J2EE Web Server, such as Tomcat. The application packaging relies on the Apache Maven assembly [19]. The WLP app is distributed as an Android application through the Google Play store. 7.5.2. Mobile app user guide To access the application the user should be authenticated. For this purpose, the AAC component is engaged and the user may decide between the WeLive credentials or the Social Login (e.g., Google) as in Figure 101:
Figure 101 – WeLive user authentication
Once authenticated, the user may directly access the list of recommended application. The proposed list initially is based on the city information associated to her profile (Figure 102). The user may combine this list with the apps of other cities using the city tabs at the bottom. The user may also perform app search and reordering (Figure 103).
D2.9 – Report on the WeLive Open Service Layer v1 page 153
Figure 102 – City based list of WeLive apps
Figure 103 – App ordering
It is possible to access the app details, by selecting a specific app line. The app details view contains: generic information about the application (title, description, provider, …), see Figure 104 community information (user ratings and comments), see Figure 105
D2.9 – Report on the WeLive Open Service Layer v1 page 154
In this view the WeLive Player app distinguishes also the state of the application, i.e., whether it has been already installed on the user’s phone. If the app has not yet been installed, the center bottom button allows the user to open the download link for this app and install it. Otherwiser, the user can directly open the application.
Figure 104 – App details
Figure 105 – Community info about app
D2.9 – Report on the WeLive Open Service Layer v1 page 155
7.6. DATA PROTECTION RELATED REQUIREMENTS
Requirement Related questions Player component
In a system like WeLive there is the Are the consent Within the WeLive Player the only situation in requirement for the consent of the form processes which we consider a consent form is when the individuals concerned. included in the user authenticates through social accounts. In system design? this case, the user provides some further data If a youngster of below 16 years about herself/himself for the purposes of better Who is designing the wishes to use online services, the personalization and service recommendation. consent form and service provider has to try to verify The user is asked a consent for the treatment of the terms of use for that parental consent has been such data. various user groups? given. The terms of use are the same used in the case of the WeLive Controller and are available In addition the controller shall be within the WeLive Player from a dedicated item able to demonstrate that consent in the lateral menu. was given by the data subject to the processing of their personal data.
The system has to provide easy How are these The data represented and managed within the access to your own data, including requirements to be WeLive Player refers to the one stored in the how their data is processed. This taken into account Citizen Data Vault (CDV). information should be available in in the system design Personal data access is restricted to the user a clear and understandable way. and in various owning the data. building blocks and Further there is a right to applications? The WeLive Player allows the user to check and portability, facilitating the modify her/his personal profile taking of the transmission of personal data from services provided by the CDV API. one service provider. The right to be forgotten issue does not apply to the WeLive Player. Individuals have also a right to erase personal data and "to be forgotten". This enables subjects to require the removal, without delay, of personal data collected or published. Individuals have the right to know How is the system Does not apply to WeLive Player since this when your data has been hacked: and its various component does not store any data. Companies and organisations must components to be notify the national supervisory monitored from this authority of serious data breaches viewpoint? as soon as possible so that users can take appropriate measures. Individuals have the right to object How is this feature Does not apply to WeLive Player since this to the processing of personal data to be taken into component does not store any data.
D2.9 – Report on the WeLive Open Service Layer v1 page 156
relating to the public interest or to account in the legitimate interests of a controller. system (citizen data This right covers the use of vault, decision personal date for the purposes of engine and 'profiling'. analytics)?
(Common safeguards covering the processing of personal data for archiving purposes where that is in the public interest and for scientific and historical research or statistical purposes.) Transfer of personal data outside This is to be taken Does not apply to WeLive Player since this the EU: the regulation lays down when figuring out component does not store any data. the rules for transferring personal the business model data to third countries and and the hosting international organizations. environments. Transfer may take place provided that a number of conditions and safeguards are met. The Act is based on “risk-based How is the overall The same considerations apply here as for the approach”: the stronger the risks security architecture WeLive controller in section 5.2.7. No additional of the activities for the personal of the WeLive? How requirements are needed since the WeLive data, the more stringent the Is the privacy by Player does not have to address any specific obligations are. Processing design-approach security issue. sensitive data (including race, applied? (see also health) is of a special concern. deliverable 5.3) Requirements include Privacy Impact Assessment and other measures needed to tackle risks.
Data protection safeguards are to be built into products and services from the earliest stage of development (Data protection by design and default). Such measures could consist inter alia of minimizing the processing of personal data, pseudonymising personal data a.s.a.p, transparency with regard to the functions and processing of personal data, enabling the data subject to monitor the data processing, enabling the controller to create and improve security features.
D2.9 – Report on the WeLive Open Service Layer v1 page 157
Any processing of personal data in This is to be taken Does not apply to WeLive Player since this the context of the activities of an when figuring out component does not store any data. establishment of a controller or a the business model processor is to be carried out in and the hosting accordance with regulation, environments. regardless of whether the processing itself takes place within the Union or not. Responsibilities between controller of the data and the processor of the data have to be defined clearly. Table 36 – WeLive Player ethical and data protection requirements
D2.9 – Report on the WeLive Open Service Layer v1 page 158
7.7. FUNCTIONAL TESTS RESULTS OF THE WELIVE PLAYER The following table shows the results of the functional tests performed against the use cases described in section 7.2.2
Test ID Name Mapped Date Tests results (Iteration #1) Date Tests results (Iteration #2) use cases (Iteration #1) (Iteration #2) (PASSED/PASSED WITH (PASSED/PASSED WITH RESERVE/NOT PASSED) RESERVE/NOT PASSED)
WLP.FT.1 Search apps WLP.UC.1 16/03/2016 PASSED
WLP.FT.2 View app details WLP.UC.2 16/03/2016 PASSED
WLP.FT.3 Change preferences WLP.UC.3 16/03/2016 NOT PASSED: user information is 31/03/2016 PASSED shown but it cannot be modified WLP.FT.4 Recommend apps WLP.UC.4 16/03/2016 PASSED
WLP.FT.5 Download app WLP.UC.5 16/03/2016 PASSED
Table 37 - WeLive Player functional tests
D2.9 – Report on the WeLive Open Service Layer v1 page 159
8. AAC BUILDING BLOCK SPECIFICATIONS The macro-requirement CBB.2 defined in [1] refers to “provision of a building block (or more building blocks) implementing the user authentication mechanisms according to the access control mechanisms identified in the WeLive building block reference model. By exploiting this building block, a developer instruments services and apps with the necessary procedures to require user authentication”. To accommodate for this requirement, the Authorization and Authentication Control (AAC) building block relies on the OAuth2.0 [6] protocol for the resource access authorization and external identity providers for the user authentication. Specifically, AAC supports integration with the identify providers made available through standard authentication protocols, such as Shibboleth, Open ID, OAuth, or CAS. The objective of AAC is twofold. First, it is used to accommodate wide range of scenarios, where the services, applications, and the final users are involved. A typical scenario represents a third-party application that requires to access one of the core-building blocks (such as the citizen data vault) on behalf of the user in order to access its profile or perform some operation. Second, the AAC architecture aims at supporting the extensibility and customizability of the platform. On the one hand, such extensions may refer to the modalities and channels used for the user identification and authentication, which may be specific to a city and its settings. On the other hand there is a need for providing a granular control over access to the new platform building blocks and services. In order to accomplish these goals, the AAC building block adopts various the OAuth2.0 protocol flows (implicit flow, authorization token flow, client flow); provides the modular architecture and configuration mechanisms for various identity provider protocols; enables the configurability of the building block resource access; provides the ways to extend the set of available resources when required by new building blocks and components. 8.1. DETAILED REQUIREMENTS Based on the macro-requirement stated above, the following detailed requirements are reported.
ID CBB.2.1
Name Authentication mechanism
Requirement Type Functional
Description Implement the user authentication mechanisms according to the access control mechanisms identified in the WeLive building block reference model
Rationale Important capabilities of the city are not publicly accessible and access control shall be adopted for them. The instrumentation of services and apps with the procedures necessary for user authentication according to the WeLive policies is a repetitive, error prone task. This requirement aims at facilitating the development by offering the possibility for developers to integrate authentication in the apps and services by invoking the functionalities of the authentication building block.
Fit Criterion One or more building blocks are available that offer mechanisms implementing (Measurable) user authentication mechanisms according to the WeLive access control policies.
D2.9 – Report on the WeLive Open Service Layer v1 page 160
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts Management of building blocks in general relies on this core building block to access if different users can actually operate upon those BBs.
Constraints The accomplishment of this requirement critically depends on the definition of (Attainable) suitable standard authentication mechanisms for WeLive access control policies. This requirement contributes to OSF.5.
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Developer identifies suitable authentication mechanisms for his/her app or services, accesses the specification of the authentication building block and exploits its functionalities to implement authentication for the app or service.
Author FBK team.
Revision V1.0, 29/02/2016
ID CBB.2.2
Name Single Sign-On
Requirement Type Functional
Description Guarantee seamless and transparent user authentication across different WeLive platform components and applications in a centralized manner.
Rationale WeLive platforms represents a complex ecosystem integrating different components and subsystems. The user accessing different components should be uniquely identified and recognized by different components.
Fit Criterion Providing mechanisms for the unified user identification and authentication, (Measurable) regardless the components the user is accessing or the authentication channels involved.
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the definition of (Attainable) suitable standard authentication mechanisms for WeLive access control policies. This requirement contributes to OSF.5.
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Developer identifies suitable authentication channels for his/her app or services, and exploits the centralized mechanism for the user identification.
Author FBK team.
Revision V1.0, 29/02/2016
D2.9 – Report on the WeLive Open Service Layer v1 page 161
ID CBB.2.3
Name Extensible authentication channels
Requirement Type Functional
Description Enable the possibility for the city to engage specific authentication means and technology solutions within the AAC.
Rationale Different cities may require that the access to certain services and resources is protected with specific security means and protocols (such as, e.g., one-time password generators, smart card, etc.). The AAC should provide suitable extensibility mechanisms accommodating for them.
Fit Criterion Possibility to integrate different types of providers and their underlying protocols, (Measurable) such as OAuth, Shibboleth, OpenID, etc.
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the definition of (Attainable) suitable standard authentication mechanisms for WeLive access control policies. This requirement contributes to OSF.5.
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors City managers define the city-specific authentication channels and exploit the AAC to embed them into the authentication process.
Author FBK team.
Revision V1.0, 29/02/2016
ID CBB.2.4
Name Extensible authorization model
Requirement Type Functional
Description Enable the possibility to define and extend authorization policies required for accessing specific components and building blocks.
Rationale Different publicly available services and resources, as well as the platform components managing them, may require different access control rules and policies. The service provider should have a way to define and engage these rules without affecting the whole ecosystem.
Fit Criterion Possibility to integrate different access policies according to the WeLive building (Measurable) block reference model.
D2.9 – Report on the WeLive Open Service Layer v1 page 162
Priority 3 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the definition of (Attainable) suitable standard authentication mechanisms for WeLive access control policies. This requirement contributes to OSF.5.
Difficulty 5 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Service providers define and engage their specific authorization policies.
Author FBK team.
Revision V1.0, 29/02/2016
Table 38 – AAC building block detailed requirements
8.2. FUNCTIONAL ASPECTS OF THE AAC BUILDING BLOCK The AAC building block relies on the OAuth2.0 [6] protocol for the resource access authorization and external identity providers for the user authentication. In this regards, the AAC architecture is extensible enabling integration of different identity providers of different types, thus addressing the CBB.2.2 requirement. Specifically, AAC supports integration with the identify providers made available through standard authentication protocols, such as Shibboleth, Open ID, OAuth, or CAS. To supports these capabilities, the OAuth2.0 protocol defines the model of permissions and the corresponding data flow as follows. Each protected operation or resource is associated to a permission (scope in OAuth2.0 terminology). For instance, the user profile read and modify operations may be associated to ‘profile.read’ and ‘profile.write’ scopes correspondingly. To perform such an operation, the caller should have the corresponding permission granted by the user and associated to the access token. The scopes may refer to user operations (like change the profile of the currently logged user) or to generic operations (like read the profiles of all the users) or both. Depending on the type of the scope the client requires to access, different OAuth2.0 protocol data flows should be involved. When the user-related scopes are involved, the access should be explicitly granted by the authenticated user through implicit or authorization code flow. As for the generic operation scopes, the client credentials flow is engaged, which does not involve the user. The access tokens emitted by the OAuth2.0 protocols are short-living. If the access to the protected resource is required only while the user is online (i.e. for short period of time), the access token should be used. If there is a need to access the resources on behalf of the user even if the user is offline or when the authentication is persisted (e.g., remember-me authentication), it is possible to use previously obtained refresh token to generate a new access token without involving the user. In the following, we consider a set of usage scenarios and their implementation with the AAC component. Authentication only. The 3rd party web app or mobile app require the user identification only, without requiring the access to the protected WeLive building blocks and resources. In this case, the AAC is used only as the user identity provider. Access to the user-related protected operations and resources. In these scenarios, the protected BBs are accessed on behalf of the user from the 3rd party application (mobile or web).
D2.9 – Report on the WeLive Open Service Layer v1 page 163
Access to the non user-related operations and resources. In these scenarios, the protected BBs are accessed without involving the user. Protect BB with AAC scopes. In this scenario, there is a need to protect a resource using AAC OAuth2.0 authorisation mechanism. 8.2.1. AUTHENTICATION ONLY SCENARIO This scenario exploits the AAC only as the way to uniquely identify the user, without requiring the access to the protected REST APIs. In this scenario, the app interacts with the AAC component to authenticate the user and to obtain the user information (cross-platform user Id, name, surname, etc). AAC enables this flow using either CAS [4] or OAuth. This scenario allows for implementing the single sign-on functionality across different WeLive components and building blocks as required by CBB.2.2 . CAS protocol provides a way for the user authentication without explicitly passing the user credentials through the 3 rd party app. The detailed description of the protocol specification may be found here: http://jasig.github.io/cas/4.1.x/protocol/CAS-Protocol.html. In this case, the protected resource redirects the user to AAC and as a result of the authentication process the protected resource obtains from AAC the user assertion document, representing the user identity (unique identifier and other relevant attributes). In case of OAuth protocol, the flow is more complex. Together with the authentication, the AAC asks the user to authorize the accessing party (the protected resource) to use his identity information. Upon successful authorization, an access token is emitted by AAC. This token may be used to access the user profile information to identity the user. 8.2.2. ACCESS TO THE USER-RELATED PROTECTED RESOURCES When an external app besides the authentication requires also the access to the protected WeLive building blocks on behalf of the user, the CAS protocol is not sufficient, as the BB access requires that the OAuth2.0 token is provided and the token is associated with the required permissions. According to the OAuth2.0 information flow, the authenticated user is asked to grant those permissions to the application and after that the corresponding token is emitted. To accomplish the requirements, the AAC relies on information flow represented in Figure 106.
Figure 106 – Protected resource access
D2.9 – Report on the WeLive Open Service Layer v1 page 164
In this flow, the user performs an access to the application in order to perform some operation or to access certain information ( App access operation). Whenever this operation involves the functionality exposed by one or more building blocks, the application needs to perform the corresponding service request ( Information access ). In case the information access requires to be protected by the building block provider, the request should be accomplished with the corresponding credentials, represented with an authorization token. The token represents The user, on behalf of which the operation is performed; The application that makes the access. Whenever the token is not available, the application has to perform the user authentication and authorization steps. More specifically, the user should be identified performing the signin/signup using one of the methods provided by the AAC ( Authenticate operation), and then the user should grant the application with the permission to access the protected resources/operation ( Authorize operation). Once these steps are done, the AAC issues the corresponding token to the application ( Obtain credentials ), and the access may be performed. To ensure that the token is correct, the protected building block may validate it against the required scope (Validate credentials ). This scenario is achieved with the OAuth 2.0 Implicit Flow or Authorization Code Flow (see below). The scenario may be engaged either in a web application (i.e., to protect a WeLive platform component or a 3rd party REST service) or in the mobile app (i.e., to authenticate the user and to grant the access to some protected resource). In either case, the client application should be registered in AAC. 8.2.3. ACCESS TO THE NON USER-RELATED PROTECTED RESOURCES When the end-user is not involved in the information exchange (e.g., in server-to-server interactions in order to retrieve generic data), it is possible to use OAuth 2.0 client credentials flow. In this case, the token is requested directly by the client application (using the private information associated to the client) and therefore is not associated to any user. Also in this case the client application should be registered in AAC in order to obtain such tokens. 8.2.4. RESOURCE ACCESS AUTHORIZATION The access control mechanism provided by AAC and its underlying protocol allows the building blocks to be protected with different policies and rules. Specifically, the model of AAC permission scopes allows the developer to use different rules for different resources: the client application should be granted these permissions in order to perform access. Depending on the flow, the permissions may be either associated to the user and therefore authorized by him or to the client flow, and therefore directly requested by the client app. To address the requirement CBB.2.4 , the access control mechanism allows for extensibility of the authorization policies, offering a way to define new permissions and associate them to different flows. In approach, the protected resource may use the API exposed by AAC in order to check the validity of the token used to perform the resource access against the required permissions. 8.3. AAC BUILDING BLOCK ARCHITECTURE AND IMPLEMENTATION 8.3.1. AAC ARCHITECTURE
D2.9 – Report on the WeLive Open Service Layer v1 page 165
Figure 107 – AAC Building Block Architecture
The AAC building block architecture is depicted in Figure 107. The AAC primarily exposes 3 endpoints: the AAC endpoint, the Data REST API, and the management console. The Authentication and Authorization endpoint implements the steps and operations foreseen by the OAuth2.0 scenarios presented above. To accomplish the authentication step, AAC relies on external Identity Providers on top of different protocols. These eternal providers may refer to social authentication channels (e.g., Google+, Facebook, Twitter, etc) and to the city-specific authentications. For this purpose, AAC provides a modular architecture, where the specific authentication modules provide protocol-specific integration, and the Authority Model component enables the integration configuration in a protocol-independent way. More specifically, the authority model defines: Attributes and identifiers returned by the Identity Provider upon successful authentication; Relation with other Identity Providers based on common attributes (e.g., on email address); The type of the interaction protocol engaged, and the related mapping properties. With this modular approach, the AAC allows for addressing the requirement CBB.2.3. The authorization step of the OAuth flow relies on the following components: The user data storage to create and update user-related records; Client data storage to retrieve and verify the information about client app making the request; Permission model to check and validate the requested permissions against client app and user; Token data storage to register the access tokens and associate them to the users, client apps, and granted permissions. The Data REST API endpoint is used to communicate with AAC in order to obtain information about the user, apps, and tokens when by the client apps. Specifically, the API allows for the following operations Retrieve the access profile of the currently logged (i.e., the basic identity information and the information retrieved from the identity providers). Access and search the profiles of different users in AAC. Retrieve the information about the client APP that makes the request. Verify whether the access token provided by the caller is valid against the specific permission scopes. To accomplish this, the Data REST API relies on the user data storage and the client data storage.
D2.9 – Report on the WeLive Open Service Layer v1 page 166
The scope of the AAC management console is twofold. First, it allows the developers to register client apps, which is necessary for participation to the OAuth2.0 authentication and authorization flows. The developer defines the use of the API (i.e., in a web app or a mobile app) as well as the permissions that should be requested/granted in order to perform the access operations. In case the present permissions are not sufficient, the developer may declare and publish new permission types through the management console (requirement CBB.2.4). 8.3.2. AAC IMPLEMENTATION AAC is implemented as a J2EE Web Application, which may be deployed and executed in any J2EE-compatible Web Server (e.g., Tomcat). It is implemented using the Spring Framework technology in order to achieve appropriate modularity and extensibility levels. The data persistence layer relies on the use of relational DB storage and exploits the Spring Data framework for the object-relational data mapping abstraction. This also facilitates the migration of the solution across deployment platform as it makes AAC agnostic to the database of choice. 8.4. DOCUMENTATION AND USER MANUAL 8.4.1. REGISTERING THE CLIENT APP The registration of the client apps is performed through the AAC Developer Console: https://dev.welive.eu/aac/dev Before accessing the console, the developer should be authenticated. Once signed in, the user can see the empty console where it is possible to register an app (Figure 108).
Figure 108 – Client app registration
To create an app, it is enough to select the application name. Note that the application name should be unique, otherwise the application will not be created. A newly created app is provided with the set of generated attributes (client_id, client_secret, client_secret_mobile) present on the overview tab (Figure 109). On the settings page it is necessary to select which methods will be used by the client for user authorization. Specifically, it is necessary to select server-side access checkbox and a valid redirect Web Server URL in case of authorization code flow; browser access checkbox and a valid redirect Web Server URL in case of implicit flow;
D2.9 – Report on the WeLive Open Service Layer v1 page 167
native app access in case of native mobile apps. It is necessary to define the set (comma-separated) of the callback URL, to which the authorization result will be redirected. It is also necessary to define which identity providers may be used for the user authentication within the app (e.g., WeLive users and or the users having Google account).
Figure 109 – Client app overview
Once the client is configured, it is necessary to define which scopes the client will target. That is, what is the maximum set of permissions that the app may require from the user. In AAC, the permissions are grouped into “services” that form logically related sets of operation and resource permissions. These model of permissions is extendible, the new permissions and services may be added for the purpose of the more accurate and controlled resource access. An important aspect is that the resources are divided into the ones owned by (or available to) the user (i.e., user resources) and those that are available to an app without involving a user (i.e., client resources). For example, the user files are of the first type, while the file storage configuration resource is of the second type. It is also important to know that some of the resources are not immediately available to the application once registered. Their access may be subject of the external approval by the data providers through some additional procedure. Once such a procedure is accomplished, the administrator will unblock the access to the resource by the application. As it is shown in Figure 110, for the services of interest of a specific application, the app developer should select the required resources and save the model. The user-related scopes are marked with the ‘U’ label, the non-related resources are marked with ‘C’, while the resources and operations available both to a single user or to the application without user grants are marked with ‘*’ label.
D2.9 – Report on the WeLive Open Service Layer v1 page 168
Figure 110 – Client app resources and permissions
Once the client app is registered and configured, it is possible to perform authorization and access the services. To facilitate the testing phase, the developer console provides means to generate both the user and the client access tokens (Figure 111). In the 'Overview' tab the 'Get client credentials flow token' link allows for generating the client access token and the 'Get implicit flow token' link allows for generating the user access token associated to the developer's account.
Figure 111 – Client app tokens
D2.9 – Report on the WeLive Open Service Layer v1 page 169
8.4.2. REGISTERING NEW PERMISSION SCOPES When necessary, it is possible to define new permission scopes for use during the AAC OAuth2.0 authorization flows. The registration of new permissions takes place with registration of new permission groups, referred to as protected services. Each service may define more permission scopes corresponding to different usage (e.g., read and write) and different targets (i.e., user-related or non user-related operations). To register a new service, it is necessary to select “My Services” menu option in the developer console:
Figure 112 – New service registration
The service is defined with service ID (alpha-numeric identifier, ‘.’), service name and description:
Figure 113 – Service details (ID, name, description)
To add new permissions, it is necessary to add a new service permission mapping . For each permission it is necessary to define permission ID and URI (alphanumeric identifier, ‘.’), name and description, define the target authority (user, client or both), whether the scope is public (default is false) and whether the client requires an explicit authorization from the platform administrator to request this scope (defaults false).
D2.9 – Report on the WeLive Open Service Layer v1 page 170
Figure 114 – Service mapping definition
Once registered, the scopes of the service may be accessed in the developer console client permissions tab.
D2.9 – Report on the WeLive Open Service Layer v1 page 171
9. LOGGING BUILDING BLOCK SPECIFICATIONS Logging building block offers a set of instruments for storing and analysing the relevant events and activities both from within the WeLive platform components and from the 3 rd part building blocks. These instruments come in the form of REST APIs and therefore programmatically available to the applications and components developed with different technologies and languages. In order to enable the detailed analysis and statistics of the platform behaviour, the Logging BB relies on a powerful and efficient query and aggregation framework, provided by the underlying event persistence infrastructure. 9.1. DETAILED REQUIREMENTS As stated in the macro-requirement CBB.1 [1], this BB should offer “to developers the capability to produce log information according to the common logging mechanisms implemented by the WeLive framework”. This requirement is refined into the following detailed requirements: to provide a common logging mechanism that allows to report relevant information in a standardized and centralized way; to facilitate the analysis of the information regarding the behaviour of the WeLive platform components and building blocks.
ID CBB.1.1
Name Standardized log reporting mechanism
Requirement Type Functional
Description Offer to developers the capability to produce log information according to the common logging mechanisms implemented by the WeLive framework.
Rationale The WeLive framework defines common logging mechanisms to be adopted by the framework components and by building blocks, services and apps. These common mechanisms provide for a centralized and uniform collection of information on the behaviour of services and apps. The exposure of these mechanisms through a building block facilitates the usage by developers.
Fit Criterion A building block is available that exposes the common logging mechanisms (Measurable) defined and implemented by the WeLive framework.
Priority 2 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the definition and (Attainable) implementation of common logging mechanisms for the WeLive platform.
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors Developer accesses the specification of the logging building block and exploits its functionalities to log messages in the building block, service, app he/she is developing.
D2.9 – Report on the WeLive Open Service Layer v1 page 172
Author FBK team.
Revision V1.0, 29/02/2016
ID CBB.1.2
Name Standardized log reporting mechanism
Requirement Type Functional
Description Offer the capability to analyse log information produced by the WeLive framework components and building blocks.
Rationale The WeLive framework defines common logging mechanisms to be adopted by the framework components and by building blocks, services and apps. These common mechanisms should facilitate the analysis of the usage of the platform.
Fit Criterion A building block is available that exposes the log analysis mechanisms defined and (Measurable) implemented by the WeLive framework.
Priority 2 (Scale from 1=low priority to 5=highest priority).
Conflicts None
Constraints The accomplishment of this requirement critically depends on the definition and (Attainable) implementation of common logging mechanisms for the WeLive platform.
Difficulty 2 (Scale from 1=low difficulty to 5=extreme difficulty).
Actors May be exploited by various roles (developers, city managers, citizens) to analyse the data produced by the platform and applications.
Author FBK team.
Revision V1.0, 29/02/2016
Table 39 – Logging building block detailed requirements
9.2. FUNCTIONAL ASPECTS OF THE LOGGING BUILDING BLOCK The functionality of the Logging building block relies on unified reference logging model. This model defines the following principles: Logging functionality is available in a centralized way using the standard communication protocol and data formats. Logging information is delivered in a unified way using a common model of a logged event. Logging information is scoped to the source that has generated it, namely logging application. 9.2.1. LOGGING MODEL The logging event model consists of the following elements: Common Event attributes, including
D2.9 – Report on the WeLive Open Service Layer v1 page 173
Application Id: the identifier of the event source that produces the information. Refers to the platform component ID or to the name of the client application or building block as registered in AAC client management console. Timestamp: the timestamp of the event occurrence. Type: a specific event type generated by the component. The possible event types are defined by the source component. Message: textual message accompanying the event. Duration: optional attribute specifying the event duration if applicable. Session: identifier used to correlate a set of events to a single session of activities (e.g., user session) Custom attributes that are defined by the specific event type model. Certain of custom attributes are common to many events and scenarios, for example: User ID: cross-platform unified user identifier, emitted by the AAC building block. Pilot or city identifier: the identifier of the pilot city engaged in managing the WeLive platform. To enable the logging operation, the Logging BB exposes a REST API that accepts the logging events in the above form. The reported events are then registered in a persistence storage in order to enable the future analysis. 9.2.2. LOG ANALYSIS To enable the analysis of logging information, the Logging BB offers a set of instruments for searching filtering and aggregating the relevant information. These instruments allow for Searching for application events filtering by time range, text search, attribute search, etc. Counting events matching certain criteria. Advanced event data aggregation using the ElasticSearch [20] aggregation framework. 9.3. LOGGIN BUILDING BLOCK ARCHITECTURE AND IMPLEMENTATION 9.3.1. LOGGING ARCHITECTURE
Figure 115 – Logging BB Architecture
The implementation of the Logging BB relies on the open source logging framework Graylog [21]. This framework incorporates the efficient information storage, retrieval, and analysis capabilities offered by
D2.9 – Report on the WeLive Open Service Layer v1 page 174
ElasticSearch engine [20], additionally offering the management and visualization console specifically tailored for the logged data representation and the APIs for inserting and accessing the logging events. The overall architecture is structured as follows. The Logging BB offers the REST API for inserting, querying, and aggregating the logging information. This API exposed by the WeLive Logger component, interacts with the GrayLog server for log event management. The latter relies on the ElasticSearch engine for the data management. The GrayLog server additionally exposes a Web interface, the Graylog management console and dashboard, for basic log data visualization and analysis. Internally, it also uses its own database for the configuration management. When the query information capabilities provided by the Graylog server are insufficient, the WeLive Logger component relies directly on the ElasticSearch engine. While operating on a lower level of information representation, this engine exposes powerful and programmable capabilities for the data retrieval and aggregation, which is essential for the functionality of the WeLive Analytics Dashboard component. The detailed description of the ElasticSearch aggregation framework is presented in [22]. 9.3.2. LOGGING BB DEPLOYMENT Figure 116 represents the deployment model of the Logging BB. Here the Logging BB that exposes REST API, is deployed as a Java Web application in a standard J2EE Web server (e.g., Tomcat). It relies on the Graylog server and on the ElasticSearch engines. The communication takes place through HTTP protocols, as both the components expose the corresponding REST APIs. The components are deployed as standalone applications, may be hosted in the same node or on any other node available to the Logging BB over the network. The persistence layer of Graylog configurations is implemented on top of Mongo DB, a No-SQL database solution [23].
Figure 116 – Logging BB deployment diagram
9.4. REST API The Logging REST API consists of the following list of methods. Push Log message . Save a log message from a specified source:
POST /welive.logging/log/{appId}
D2.9 – Report on the WeLive Open Service Layer v1 page 175
{ "msg":"Resource metadata accessed", "appId":"ods", "type":"ResourceMetadataAccessed", "timestamp": 1457110490000, "custom_attr": { "ResourceID": "5b750b42-2321-474c-b16c-0d2482aeb72a", "UserID":"5", "ResourceType":"JSON" } }
Query log messages. Perform search for message logs of the specific application.
GET /welive.logging/log/{appId} Accept: application/json from=
{ "offset": 0, "limit": 150, "data": [ { "appId": "ods", "type": " ResourceMetadataAccessed", "msg": " Resource metadata accessed", "timestamp": 1444732794782, "custom_attr":{ "ResourceID": "5b750b42-2321-474c-b16c-0d2482aeb72a", "UserID":"5", "ResourceType":"JSON" } } ], "total_results": 1 }
Count log messages . Count messages of the specific application matching the specified criteria.
D2.9 – Report on the WeLive Open Service Layer v1 page 176
GET /welive.logging/log/count/{appId} Accept: application/json
from=
{ "total_results": 1 }
Aggregate log messages . Returns aggregated statistics data according to the ElasticSearch aggregation model and syntax [20].
POST /welive.logging/log/aggregate/{appId} Accept: application/json Content-type: application/json
{ "_source" : false, "size" : 0, "aggs" : { "agg1" : { "sampler" : { "field" : "message" } } } } This method returns the aggregated information about the events:
{ "took": 14, "timed_out": false, "_shards": { "total": 5, "successful": 5, "failed": 0 }, "hits": { "total": 1564, "max_score": 0,
D2.9 – Report on the WeLive Open Service Layer v1 page 177
"hits": [] },
"aggregations": { "agg1": { "doc_count": 0 } } }
D2.9 – Report on the WeLive Open Service Layer v1 page 178
10. REGISTRY BUILDING BLOCK SPECIFICATION The Registry Building Block exposes the WeLive Marketplace searching APIs in order to get the other tools able to search and reuse the artefacts published into the platform. The artefact is a software component that could belong to three service subtypes: building block, dataset or public service: Public Service Application (PSA) is delivered in the form of gadgets compliant with “Open Social gadget Specifications and is generated through the Visual Composer component. Building Block is a web service that implements the WeLive Building Block API specification and could be deployed into the WeLive Open Service Framework (OSF). Dataset correspond to value-added datasets (private or public coming from a Public Administration) and could be published both at WeLive’s Open Data Stack (ODS). According to the WeLive service co-creation approach, in order to be used into the WeLive scenario, each artefact must be formal described and published into the Marketplace. In order to promote the usage and the diffusion of the artefact, the Registry Building Block exposes the following APIs [24].
Type Signature Description
GET /mkp/get-all-artefacts/pilot-id/{pilot- Get all building blocks and datasets id}/artefact-types/{artefact-types} published in the Marketplace filtered by pilot and/or by type
GET /mkp/get-artefact/artefactid/{artefact-id} Get a single artefact by its unique identifier
GET /mkp/get-artefacts-by-ids/ids/{ids-list} Get a list of artefacts by their unique identifiers
GET /mkp/get-artefacts-by- Get artefacts published in the keywords/keywords/{keywords}/pilot- Marketplace which contains a set of id/{pilot-id}/artefact-types/{artefact-types} specific keyword
Table 40 – Registry BB APIs
The following is the response schema model adopted by the Registry BB APIs. { "artefacts": [0………. { "artefactId": 0, "name": "string", "description": "string", "interfaceOperation": "string", "type": "string", "typeId": 0, "rating": 0, "url": "string", "geteId": 0, "comments": [
D2.9 – Report on the WeLive Open Service Layer v1 page 179
{ "text": "string", "creation_date": "2016-03-11T11:07:13.231Z", "authro_ccUid": 0 } ] } ] }
Figure 117 – Registry BB APIs
The following is the flow performed by the Visual Composer to search and import an artefact: 1. The Visual Composer invokes the Registry BB APIs in order to search BBs and dataset into the Marketplace. 2. The Registry BB returns to VC the BBs and dataset information list that match the searching criteria. 3. The modeller select the dataset that matches the mashup project requirements. 3.1. The VC stores the dataset information (ArtefactId, Name, Description, DatasetId, ResourceId, Dataset schema) to be retrieved during the mashup composition. 4. The modeller select the BB that matches the mashup project requirements 4.1. The VC stores the BB information (ArtefactId, Name, Description) to be invoked during the mashup composition. 4.2. The VC downloads locally the WADL/WSDL to be used during the mashup execution. 5. The modeller drag and drop the imported artefact into the workspace and continue the mashup composition. The following figure depitcs the interaction among a WeLive tool and the Registry BB.
Figure 118 – Searching and import flow performed by the Visual Composer
D2.9 – Report on the WeLive Open Service Layer v1 page 180
11. QUERY MAPPER SPECIFICATION The internal architecture of the Query Mapper module is depicted in Figure 119. There are two different use case scenarios, consumers and producers of information, although it is possible that the same client could fit both roles acting as a prosumer of information.
Figure 119 – Query Mapper internal architecture If the client acts as a data consumer the process begins with the client sending a SQL query to the Query Mapper. Then, the query is sent together with the registered data source’s identifier, which is used internally by the Query Mapper to retrieve the associated mapping. In order to improve the clarity of the diagram, the data source registration, mapping storage and retrieval processes are not completely represented in the figure. After obtaining the mapping description and, depending on the data source type, the Query Mapper performs the required transformations and/or redirects the query to obtain the data from the corresponding source. Currently, the module supports four data source types: SPARQL, JSON, CSV and relational databases. SPARQL. Data sources available at SPARQL endpoints can be accessed through the unified mechanism to query and update them. In this case, SQL queries and updates are transformed to their SPARQL or SPARUL (SPARQL Update Language) equivalent statements and executed against the associated endpoint. JSON. Any resource (web or local) available as JSON file can be accessed through the Query mapper. The JSON data source is analysed and its schema extracted to provide a relational view of the data. As this type of data source is usually available as a static file or provided by a database management system that does not allows updates, the Query Mapper provides support to locally store the user updates within the platform. This user data is added with the same schema as of the original JSON file and can be queried by using the same data source identifier. However, to control the provenance of the data, the Query Mapper annotates contributed data to allow future consumers to distinguish it from the original source’s one.
D2.9 – Report on the WeLive Open Service Layer v1 page 181
CSV. Any resource (web or local) accessible as a CSV file can be also registered through the Query Mapper. The process is similar to the one explained before for JSON data sources, however, in this case the relational view is obtained from the CSV structure. DB. The module also offers the possibility to connect with relational databases managed by a RDBMS (particularly PostgreSQL, MySQL or SQLite). With relational databases, which are directly compatible with SQL queries, the Query Mapper only redirects the query, or the update, to the corresponding database manager. This functionality is provided to offer a mechanism to facilitate the connection of legacy data sources within the platform, easing the migration to the Smart City’s Open Data ecosystem. As show in Figure 119, the Query Mapper manages two different internal storages: the first one contains relational representations of the schema and data of JSON and CSV datasets; while the second one stores user data, added or modified by updates from other users, which can be queried as any other data source. In addition, data can be merged and returned in the same query with the original data provided by the original data source. The next sections add a more detailed explanation about how each data source type is managed by the Query Mapper, including a description about which is the information required to be provided for each registered data source and how the module performs the storage and maintenance of user data. Relational data sources are not detailed, as the Query Mapper only applies a query or update redirection to the data source’s RDBMS and transforms the data response with the same procedure used with data obtained from mapped CSV or JSON data sources. 11.1. JSON DATA SOURCES The Query Mapper requires some information to access data sources in JSON format. Figure 120 shows an example of the mapping description that is required by the module to connect with a JSON file. The current implementation of the Query Mapper uses JSON as the language to express mappings according to the canonical form adopted within the project, but it should not be confused with the format of the mapped data source. The mapping attribute , which in this example has the value of “json”, is an implementation specific attribute used by the Query Mapper to identify the data source as JSON resource. uri: this attribute specifies the URI of the JSON file to be used as the data source. root: defines the path of the JSON element where the mapping will start. Some JSON files contain header attributes that do not contain interesting information to be mapped. The Query Mapper expects that the specified element will contain an array of objects with a repeated structure. In the example shown in the figure, the root attribute has the value “results/docs”, specifying that the mapping starts in the docs element inside the results attribute. It could be possible to select the JSON root element using the empty path “/”. key: this property selects, from the set of mapped objects, the attribute to be used as the primary key for the main table in the local storage created by the Query Mapper module. If the mapped objects, as specified by the root property, do not contain an attribute that can be used as the primary key, it is possible to ask the Query Mapper to generate a sequential identifier by using the "_id" value for this attribute. table: this attribute of the mapping description allows selecting the name of the main table that is created by the query mapper when extracting the schema and data of the mapped data source. refresh: some JSON data sources can change periodically, as they could provide information coming from sensors or other dynamic sources. As the Query Mapper extracts the data contained in the
D2.9 – Report on the WeLive Open Service Layer v1 page 182
mapper JSON resource to create the relational view, this attribute defines the interval to retrieve the new data and update the internal structures. charset: this attribute is used to declare the character encoding of the data source in order to solve inter-operability issues that can arise when clients exploit the data through the platform.
Figure 120 – JSON data source example mapping and relational tables Using the information contained in the mapping description, the Query Mapper connects to the resource containing the data, in this case a JSON file, downloads the data and analyses it, extracting its schema in order to create a relational view of the data source, which is populated with a copy of the data. The Query Mapper extracts the JSON structure and creates tables representing the same data structure. However, some conversion needs to be applied in order to normalise the resulting database: The list of objects, specified by the root property of the mapping, is iterated and all literal attributes (strings and numbers) are converted to their relational equivalent representation. Finer data type detection is applied to check if strings can be represented as dates or if numbers are integer or float types. Each object is mapped to a table, whose schema contains all literal properties as columns with the detected type. For those properties that have not a literal type, but contain an array of other objects, a new child table will be created, applying a recursive process. This table is connected to its parent using a special identifier column added to the child table. If the JSON property contains an array of literal values, a new table containing a single column will be created, using the same foreign key mechanism to connect the newly created table with the one containing the parent object.
D2.9 – Report on the WeLive Open Service Layer v1 page 183
As an example of relational view creation, Figure 120 shows the tables generated as result of the schema extraction and data population. First, the table “example_data” defines two columns, “key1” and “key2” of string type, which created from the literal properties of the objects contained in the array defined by the “root” property of the mapping description. As each object contains not only simple literal properties but also other objects, the process is recursively applied creating other related tables. Therefore, table “example_data_key3” is created by using the literal properties of the objects defined by the “key3” attribute of the main array of objects. As client could require reconstructing the original data structure, the “example_data_key3” table is connected to its parent using its unique identifiers using the “parent_id” column of the child table. Child tables also contain a new inserted column “_id” that is used to allow unique identification of rows inside child tables. The last table, “example_data_key3_key3” is created using the arrays of literal values defined by the nested objects. In this case, in order to normalise the relational schema, the values are not stored as a comma separated list of values but, instead, they are inserted as different rows that are connected to their parent objects with the help of the new inserted “parent_id” column. As can be seen in the example, the name of the tables is automatically created using the name of the connected properties. The main table is called “example_data” as this was the name specified in the mapping description. However, the names of the child tables are created by a combination of the parent table’s name and the name of the property being extracted to a new table. In the current Query Mapper’s implementation, these tables are stored inside an RDBMS internally managed by the module, which will execute the SQL queries send by the users and obtain the required data in the selected format. 11.2. CSV DATA SOURCES When the Query Mapper is connected to a CSV data source, the process is much simpler than when extracting JSON data sources; the structure of CSV files does not allow the introduction of nested objects, with a known common structure as JSON does, and they directly resemble the structure of a simple table with multiple columns. Although these columns can contain complex data, e.g. a list of space separated values, this structure data dependant and cannot be easily detected to extract the data into multiple tables, as in the case of JSON data sources. Figure 121 shows an example of the mapping description required to connect the Query Mapper with data sources in CSV format. In this case, the mapping attribute has the “csv” value, which is used by the module to identify the data source as a CSV resource. The rest of the attributes have the following meaning: uri: this attribute specifies the URI of the CSV file to be used as the data source, and local files can be referenced using local system routes. key: this property selects, from the set of columns in the CSV file, the one to be used as the primary key in the resulting relational view. delimiter: the character used to separate the different columns in the CSV resource, which enables to support TSV, or other special characters such as the semi-colon. table: as in the case of JSON data sources, this attribute specifies the name of the table created by the Query Mapper module. refresh: CSV data can be dynamically created by the data source, this parameter defines the update interval used to retrieve any changes in the data. charset: this attribute selects the character encoding of the data source, which is used to resolve interoperability issues with the data.
D2.9 – Report on the WeLive Open Service Layer v1 page 184
Figure 121 – CSV data source example mapping and relational tables The example shown in Figure 121 represents a situation where the data is provided by a simple CSV. The Query Mapper extracts the schema and the data, creating a new table with the name specified by the mapping description containing the data provided by the CSV data source. The type of the table columns is declared by analysing the type of the values contained in the CSV for each of the columns, following an identical procedure as the one applied for JSON resources. In this case, the mapping defines the “key” attribute of the mapping description with the special value of “_id”, which results in the creation of an ad hoc key for the relational table containing sequential identifiers. The resulting table, with the extracted data, is stored into a local RDBMS, which allows executing direct SQL queries against the data. 11.3. SPARQL DATA SOURCES The Query Mapper can also be used to connect with SPARQL endpoints, which is useful to provide a simpler mechanism to access data that is accessible only in RDF format. In this case, the required mapping is more complex than the one used for JSON and CSV data sources, explained in the previous section, because the Query Mapper needs some extra information to map between the relational and semantic view of the data. Specifically, the mapping description for a SPARQL endpoint expresses the connection between the relational view and the RDF model. It contains the correspondence among the classes and properties of the semantic view and the tables and attributes of the relational one. Figure 122 shows an example of the mapping file required to connect with SPARQL endpoints.
D2.9 – Report on the WeLive Open Service Layer v1 page 185
Figure 122 – SPARQL endpoint mapping description Particularly, the mapping description contains the URL of the SPARQL endpoint, specified by the sparqlEndpoint attribute, and the name of the RDF graph that is going to be translated into a relational view. The graph name, specified by the graph property in the mapping, could be left empty, which means that the default graph for that endpoint will be used. The mapping also contains a list of table objects, one for each relational table that will be created in the view. Each table object, contained in the array of tables, defines the following attributes: name: the name that SQL queries will use when referring to the relational table. It must be unique inside the mapping. It is possible to use the special value "manytomany", which is used to specify an N to M relationship mapping table. rdfClass: the URI of the RDF class that is mapped to this table. All instances from the RDF model belonging to the class will appear as rows of the table. primaryKey: a list of column names composing the primary key of the table. columns: list of column descriptions containing information about how RDF class properties are mapped to table attributes. Each column description contains the following elements needed by the Query Mapper to map the RDF properties into attributes: name: the name that SQL queries will use when referring to the column. It must be unique inside each table description. rdfProperty: the URI of the property, in the RDF model, that maps to this column. type: the type of the mapped column, which can be one of the following: BOOLEAN, CHAR, BYTE, FLOAT, DOUBLE, SHORT, INT, LONG, STRING, when mapping RDF Data Object properties. It can also have the special value "objectproperty", which is used to indicate that the mapped RDF property is an Object Property and, as defined by RDF, relates to another object using an URI as the identifier.
The SQL query is transformed to a SPARQL query, which can be executed on the selected endpoint, by parsing the string submitted by the user. Currently, the translation process supports SELECT statements and the following clauses: ALL, DISTINCT, WHERE, GROUP BY, HAVING, ORDER BY and LIMIT, which we think could be enough to fulfil the client needs when retrieving data.
D2.9 – Report on the WeLive Open Service Layer v1 page 186
Figure 123 – SQL to SPARQL translation example 11.4. RELATIONAL DATA SOURCE MAPPING This mapping type enables to connect with relational data sources and redirect SQL queries to the associated RDBMS.
Figure 124 – Structure of relational database mapping file The mapping contains the following fields: mapping: This attribute must contain the value database. dbType: Specifies the vendor of the RDBMS that is connected with this mapping. Supported types are SQLite, PostgreSQL and MySQL. host: The IP/name of the machine where the database is located on. database: The name of the database. For SQLite database it should the path of the database file. user: User with privileges on the database. Read only datasets will require only select privileges while performing writes will require to provide update support. Not required for SQLite databases. pass: The password for the previous user. Not required for SQLite databases. 11.5. REST API The Query mapper offers its functionality through a REST API that can be invoked by client applications in order to access and update the available datasets. Figure 125 contains a capture of the Swagger interface of the different methods that constitute the Query Mapper interface.
D2.9 – Report on the WeLive Open Service Layer v1 page 187
Figure 125 – Query mapper REST API A summary of the functionality of each method is the following: GET /dataset/{dataset}/resource/{resource}/mapping. This method obtains the mapping associated with the registered resource. Previous sections explain the supported data sources and its required mapping descriptions. POST /dataset/{dataset}/resource/{resource}/mapping. The method enables to update the mapping associated with the resource. GET /dataset/{dataset}/resource/{resource}/mapping/info. This method obtains a description of the mapped resource in relational format. It is useful to show all data sources using a common structured format. POST /dataset/{dataset}/resource/{resource}/query. This method enables to perform an SQL query against the registered resource using the corresponding mapping. GET /dataset/{dataset}/resource/{resource}/reset. This method resets the internal data that the query mapper contains about the registered resource. This method is usually called after the mapping associated with the resource has been updated. POST /dataset/{dataset}/resource/{resource}/update. This method enables to update the data contained in the registered data source. POST /dataset/{dataset}/resource/{resource}/update/json. As the previous method, it enables to update the data associated with a registered resource but, in these case, using JSON format for the data.
D2.9 – Report on the WeLive Open Service Layer v1 page 188
12. SOCIAL WRAPPER SPECIFICATIONS Social wrapper is a web service that extracts data from social networks, namely Twitter. Twitter provides unstructured info and based on social network wrapper it will be possible to create a new or extending datasets (compiling the selected tweets in successive dates) that talk about certain topics in a given period within a given area. The results of social wrapper is integrated into the ODS. For accessing the social network, REST APIs are created. A library of useful scripts to undertake social network processing is provided, e.g. module to extract all tweets including different filters: A list of geolocations (desired latitude, longitude and radius). A list of hashtags. A list of Twitter accounts. Desired time period (since some predefined date). Keywords and terms (string). Different combinations of these filters. One optional parameter is defined: maxTweets for maximum number of tweets that API return (default values is set on 1000). BoundingBox is also set: GetGeoSearch which for defined parameters return list of places with coordinates that describe the boundary of that place.
From each tweet, the following information will be obtained: Text of the tweet. TweetID UserID User who has written the tweet. Date time of creation of the tweet. Number of retweets. Following are the details of APIs created for extraction of data from social network Twitter. By calling this API result will be list of tweets that corresponds to requested query with the following parameters: latitude, longitude, radius of observed area, desired string, maximal number of Tweets:
Field Value
Title Get tweets
URL api/twitter/GetTweets
Method GET
URL Params Required: latitude=[decimal number] example: latitude=44.8141868
latitude=[decimal number] example: longitude=20.4213967
radius=[decimal number] example: radius=5
Optional
D2.9 – Report on the WeLive Open Service Layer v1 page 189
searchQuery=[string] example: searchQuery =shopping
maxTweets=[integer] Default value is 1000 example: maxTweets =50
Example http://srv.dunavnet.eu/ModuleWeliveSocialAPI/api/twitter/GetTweets?latitude=44.8141868 Request &longitude=20.4213967&radius=5&searchQuery=shopping&maxTweets=100
Response [ { "Text": "#SW \o/ (@ Ušće Shopping Center - @usceshopping in Belgrade, Central Serbia) https://t.co/1g1ymhNnmg", "TweetID": 684420126763016192, "CreatedAt": "2016-01-05T18:04:08+01:00", "CreatedBy": "markonnee", "UserID": 46709523, "Hashtags": [ { "Hashtag": "SW" } ], "IsRetweet": false, "Retweet": null, "RetweetCount": 0 } ]
Calling this API, result will be the list of Tweets that corresponds to the desired string since the desired date. Also maximum number of Tweets can be defined.
Field Value
Title Get tweets by since date
URL api/twitter/GetTweetsBySinceDate
Method GET
URL Params Required: searchQuery=[string] example: searchQuery=novi sad
sinceDate =[date] example: sinceDate=12.25.2015 dateFormat=mm.dd.yyyy
Optional
D2.9 – Report on the WeLive Open Service Layer v1 page 190
maxTweets=[integer] Default value is 1000 example: maxTweets =50
Example http://srv.dunavnet.eu/ModuleWeliveSocialAPI/api/twitter/GetTweetsBySinceDate?searchQ Request uery=novi sad&sinceDate=12.25.2015&maxTweets=10
Response [ { "Text": "RT @jadrankaJovisic: Zaklonili ljudima sunce.Bukvalno.Slovačka redakcija Radija Novi Sad i bilbord koji potpuno prekriva prozore #novisad h…", "TweetID": 687276217578434561, "CreatedAt": "2016-01-13T15:13:13+01:00", "CreatedBy": "radesantrac", "UserID": 448365366, "Hashtags": [ { "Hashtag": "novisad" } ], "IsRetweet": true, "Retweet": { "CreatedAt": "2016-01-13T11:02:30+01:00", "CreatedBy": "jadrankaJovisic", "UserID": 44851682 }, "RetweetCount": 15 }, ]
This API returns the list of the cities, places with coordinates that defined boundaries of these places, i.e. BoundingBox for desired parameters.
Field Value
Title Get geo search
URL api/twitter/GetGeoSearch
Method GET
URL Params Required Some parameters require existing of other example: parameter latitude requires longitude, and vice versa.
It is mandatory to provide at least one parameter, i.e. either query or latitude and longitude
Optional:
D2.9 – Report on the WeLive Open Service Layer v1 page 191
query=[string] example: query=novi sad
latitude=[string] example: latitude=43.25192
longitude=[string] example: longitude=-2.93556952
granularity=[string] Default value is neighborhood example: granularity =city list of values: poi, neighborhood, city, admin or country
Example http://srv.dunavnet.eu/ModuleWeliveSocialAPI/api/twitter/GetGeoSearch?latitude=43.2519 Request 2&longitude=-2.93556952&granularity=city
Response [ { "Id": "cd43ea85d651af92", "Url": "https://api.twitter.com/1.1/geo/id/cd43ea85d651af92.json", "PlaceType": "city", "Name": "Bilbao", "FullName": "Bilbao, País Vasco", "CountryCode": "ES", "Country": "España", "Centroid": [ -2.93556952, 43.25192 ], "BoundingBox": { "Type": "Polygon", "Coordinates": [ [ [ -2.98601031, 43.2136536 ], [ -2.98601031, 43.2901459 ], [ -2.88032484, 43.2901459
D2.9 – Report on the WeLive Open Service Layer v1 page 192
], [ -2.88032484, 43.2136536 ], [ -2.98601031, 43.2136536 ] ] ] } } ]
D2.9 – Report on the WeLive Open Service Layer v1 page 193
13. WEB SCRAPER SPECIFICATION Web scraper is a web service that extracts data from HTML web pages. Web scraper allow the registration of a desired URL (that should be parsed), a script including scraping logic, and JSON file containing the extracted data. The user has to provide a script for parsing the webpage, since different script has to be developed for each webpage to be parsed and script should include the type of output expected (regular expressions that applied to process contents). The results of the Web scraper are integrated into the ODS, i.e. a new dataset in the ODS will be created with the extracted data. Here is the example of API returns data from desired/searched HTMP page (URL) for defined parameters:
Field Value
Title Get scraping for url
URL api/scraper/GetScrapingForUrl
Method GET
URL Params Required: url=[string] example: url=http://www.futbol24.com/team/spain/rcd-espanyol
xpath=[string] example: xpath=/html/body/div[1]/div[5]/div[5]/div[11]/div[2]/table/tbody/tr
Optional tmcsv=[string] example: tmcsv =pos,team,gp,pts,w,d,l,gf,ga,plus/minus
Parameter for mapping of columns names Example: column_1 = pos, column_2=team, column_3=gp ...
Example http://srv.dunavnet.eu/ModuleWeliveSocialAPI/api/scraper/GetScrapingForUrl?url=http://w Request ww.futbol24.com/team/spain/rcd- espanyol&xpath=/html/body/div[1]/div[5]/div[5]/div[11]/div[2]/table/tbody/tr&tmcsv=pos,t eam,gp,pts,w,d,l,gf,ga,plus/minus
Response [ { "pos": "1", "team": "Atlético Madrid", "gp": "19", "pts": "44", "w": "14", "d": "2", "l": "3", "gf": "27", "ga": "8",
D2.9 – Report on the WeLive Open Service Layer v1 page 194
"plus/minus": "19" } ]
D2.9 – Report on the WeLive Open Service Layer v1 page 195
14. CONCLUSIONS This deliverable described the functional and technical aspects of WeLive Open Service layer by providing detailed descriptions of its component’s requirements and use cases, sequence diagrams and by describing its component’s functionality and interoperability with other components of the WeLive framework. The deliverable showed how the Open Service layer complements the Open Data layer in helping the stakeholders of a city to realize new added value services with the provisioning of complete solutions to support the development, publication and distribution of such services. The key elements of this layer of the WeLive architecture is its two-fold role of enabling a factorization of the IT capabilities offered by a city into components, and of guaranteeing that such components can be easily accessed, reused and combined with each other to give place to composite services and apps. The different instruments provided by the Open Service layer to fulfil this double role were fully described: The Building Block model; The Visual Composer, the WeLive Controller and the WeLive Player tools; The Core Building Blocks.
The deliverable described the first realization of the Open Service layer and of all the instruments just mentioned covering functional aspects, requirements and the use cases; analysing technical aspects, interoperability issues and deployment solutions; providing specifications and user manuals; and addressing ethical and data protection issues when necessary. In addition, this report also contains the results of the functional tests performed against its implementation, which has allowed to detect errors and problems and to confirm that the developed implementation of the Open Service layer meets the specified requirements.
D2.9 – Report on the WeLive Open Service Layer v1 page 196
15. ABBREVIATIONS
AAC Authentication and Authorization Controller
API Application Program Interface
BB Building Block
CAS Central Authentication Service
CDV Citizen Data Vault
CNS Cloud’N’Sci Ltd.
CSS Cascading Style Sheets
CSV Comma-separated values
FBK Fondazione Bruno Kessler
FT Functional Test
HTML HyperText Markup Language
IFTTT IF This Then That
JSON JavaScript Object Notation
MKT Marketplace
ODS Open Data Stack
OIA Open Innovation Area
RDF Resource Description Framework
REST Representational state transfer
SD Sequence diagram
SOAP Simple Object Access Protocol
SPARQL SPARQL Protocol and RDF Query Language
SQL Structured Query Language
UC Use case
UML Unified Modeling Language
USDL Unified Service Description Language
VC Visual Composer
WADL Web Application Description Language
XML eXtensible Markup Language
D2.9 – Report on the WeLive Open Service Layer v1 page 197
16. REFERENCES
H2020-INSO-2014, WeLive project Consortium, “D1.5 – WeLive framework requirements”, [1] September 2015 Object Management Group (OMG), “Unified Modeling Language (UML)” standard, [2] http://www.uml.org
[3] H2020-INSO-2014, WeLive project Consortium, “D2.11 – Open Service Layer v1”, March 2016
[4] CAS Protocol. https://jasig.github.io/cas/4.0.x/protocol/CAS-Protocol.html
[5] OpenID. http://openid.net/
[6] OAuth 2.0 Protocol. http://oauth.net/2/
[7] Shibboleth. https://shibboleth.net/
H2020-INSO-2014, WeLive Annex I to the GA “Description of Action” (645845). WeLive – A [8] neW concept of pubLic administration based on citizen co-created mobile urban services, February 2015. CLIPS EU Project - Cloud of Public Services, http://www.clips-project.eu/, Accessed in April [9] 2014 H2020-INSO-2014, WeLive project Consortium, “D2.1 – Report on the WeLive Open [10] Innovation and crowdsourcing tools v1”, November 2015
[11] Open Social Gadgets Specifications, https://opensocial.atlassian.net/wiki/display/OSD/Specs
[12] SPRING framework Community, “The java SPRING framework”, https://spring.io/ Hibernate Community, “Hibernate open source Java persistence framework [13] ”http://hibernate.org/ [14] PostgreSQL community, “Postgres v.9.1 DBMS”, http://www.postgresql.org/ [15] JQuery Foundation, “JQuery Library v.1.10”, https://jquery.com/ [16] Draw2D-Touch Community, “Draw2D-Touch framework”, http://www.draw2d.org/draw2d/ [17] Apache Cordova. https://cordova.apache.org/ [18] Ionic Framework. http://ionicframework.com/ [19] Apache Maven. https://maven.apache.org/ [20] ElasticSearch. https://www.elastic.co/ [21] Graylog. https://www.graylog.org ElasticSearch aggregation framework. [22] https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html [23] MongoDB. https://www.mongodb.org/ [24] Marketplace API on Swagger: https://dev.welive.eu/dev/swagger/#/mkp
D2.9 – Report on the WeLive Open Service Layer v1 page 198
17. COMMENTS FROM EXTERNAL REVIEWERS 17.1. CNS March 30, 2016
Score Issue Yes No Comments (1=low to 5=high) Is the architecture of the document X 4 correct? Does the architecture of the document X 5 meet the objectives of the work done? Does the index of the document collect X 4 precisely the tasks and issues that need to be reported? Is the content of the document clear X 4 and well described? Does the content of each section X 5 describe the advance done during the task development? Does the content have sufficient X 4 technical description to make clear the research and development performed? Are all the figures and tables X 2 Images without caption in numerated and described? sections 4.1, 7.5 and 8.2.2. Tables without caption in sections 3.1, 5.2.2.1, 5.2.7, 5.2.8, 6.2.1, 6.2.3, 6.7, 7.2.1, 7.6, 7.7, 8.1, 8.4, 9.1. Image numbering problems in sections 3.2, 6 and 10. Are the indexes correct? X 4 Section number 8.4.1 duplicated. Invalid section reference in 3.3. Is the written English correct? X 4 Section 12 refers to social network “Tweeter”, should be “Twitter”? Main technical terms are correctly X 4 Mostly OK, but in some cases referenced? the term is used many times in the document before it is referred (e.g. CAS) and some terms are not referenced at all (e.g. Shibboleth, OpenID). Glossary present in the document? X 3 Abbreviations are not in alphabetical order, which makes them hard to find. Many frequently referred abbreviations are missing from the table, such as BB, RDF, USDL, WADL, FBK, CNS, …
Pauli Misikangas [email protected]
D2.9 – Report on the WeLive Open Service Layer v1 page 199
CEO, Cloud’N’Sci Ltd 17.2. DNET March 30, 2016
Score Issue Yes No Comments (1=low to 5=high) Is the architecture of the document X 5 correct? Does the architecture of the X 5 document meet the objectives of the work done? Does the index of the document X 5 collect precisely the tasks and issues that need to be reported? Is the content of the document clear X 5 and well described? Does the content of each section X 5 describe the advance done during the task development? Does the content have sufficient X 5 technical description to make clear the research and development performed? Are all the figures and tables X 4 Few tables and figures are not numerated and described? numerated Are the indexes correct? X 4 I’ve fixed some indexes that I’ve found incorrect Is the written English correct? X Main technical terms are correctly X 5 referenced? Glossary present in the document? X 5
Mirjana Nikolic [email protected] DunavNET
D2.9 – Report on the WeLive Open Service Layer v1 page 200