Assistant for Quality Check during Construction Execution Processes for Energy-efficienT buildings
WP2 – Concept, Requirements and Specification
D2.8: Technical Specification and Mockups
Deliverable Lead: ANS
Contributing Partners: ASC, CYPE, IDS, IEC, IBP, TIE
Delivery Date: 12/2015
Dissemination Level: Public
Version 1.0
This deliverable is regarding the technical specification of the ACCEPT system. This is created based on the functional specification and the architecture of T2.5. It will define the interfaces, protocols and class/package structures including definitions of communication detailed between the components and their sequences.
Public Technical Specification ACCEPT WP2 and Mockups
Document Status
Deliverable Lead Jesús Martínez, ANS
Internal Reviewer 1 Michael Krummen, Nicolas Meyer, ASC
Internal Reviewer 2 Vadim Petrenko, TIE
Type Deliverable
Work Package WP2: Concept, Requirements and Specification
ID D2.8: Technical Specification and Mockups
Due Date 31.12.2015
Delivery Date 28.12.2015
Status For Approval
Note This deliverable is subject to final acceptance by the European Commission.
Disclaimer The views represented in this document only reflect the views of the authors and not the views of the European Union. The European Union is not liable for any use that may be made of the information contained in this document. Furthermore, the information is provided “as is” and no guarantee or warranty is given that the information is fit for any particular purpose. The user of the information uses it at its sole risk and liability.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 2 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Project Partners
ASC – Ascora GmbH, Germany ANS – AnswareTech S.L., Spain
IDS – University of Liege, Belgium EPI – EPITESSERA Architects, Cyprus
CYPE – CYPE SOFT, S.L., Spain INGL – Ingleton Wood LLP, United Kingdom
FER – Ferrovial Agroman, Spain TIE – TIE Nederland N.V., The Netherlands
EJD – Entreprises Jacques Delens S.A., Belgium
IBP – Fraunhofer-Gesellschaft zur Förderung IEC – Fraunhofer Italia Research der angewandten Forschung e.V., Germany Konsortialgesellschaft mbH, Italy
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 3 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Executive Summary This deliverable provides a detailed technical view of the whole ACCEPT System. For this purpose, the deliverable is divided into four main parts: The system overview that provides a general vision over the complete system, showing its components and the dependencies between them The major design principles that describe the general aspects of security, data formats, communication and interaction, extensibility and testing of the technical part of the system The technical specification of the ACCEPT System that is the most important section in the deliverable. It depicts decisions made about the development of the different components of the ACCEPT System. Each component is described in detail, including an overview about the component, the major design decisions to be taken into account to develop the component, a technology comparison of the different hardware, tools, frameworks or API’s that each component can use and a selection of the hardware/software chosen for the development; and two sections about the interfaces that each component provides to the rest of the ACCEPT System and what services are consumed by each component from the interfaces offered by the others. Finally, the Mockups for the ACCEPT clients tools for the Site Manager Application, the Construction Operator Application and the Dashboard are described. These mockups are going to be presented to the final users for validation This deliverable provides the guidelines for the development of the ACCEPT System (WP3, WP4, WP5 and WP6).
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 4 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table of Contents
1 Introduction ...... 15 1.1 ACCEPT Project Overview ...... 15 1.2 Deliverable Purpose, Scope and Context ...... 15 1.3 Document Status and Target Audience ...... 16 1.4 Abbreviations and Glossary ...... 16 1.5 Document Structure ...... 16 2 System Overview ...... 17 2.1 Architecture ...... 17 2.2 Components ...... 17 2.3 Dependencies between Components ...... 19 3 Major Design Principles ...... 20 3.1 Security and Privacy ...... 20 3.2 Data Formats ...... 20 3.3 Communication and Interaction ...... 21 3.4 Extensibility...... 21 3.4.1 Back-end Extensibility ...... 22 3.4.2 Client Extensibility ...... 22 3.4.3 Market Place Extensibility ...... 22 3.5 Testing ...... 22 4 Technical Specification ...... 24 4.1 Overall ...... 24 4.1.1 Overview ...... 24 4.1.2 Major Design Decision ...... 24 4.1.3 Technology Comparison ...... 24 4.1.3.1 Technology Selection ...... 25 4.1.4 Component Structure ...... 26 4.1.5 Interfaces ...... 26 4.1.6 Consumed Services ...... 26 4.1.7 Summary...... 26 4.2 Site Manager Application ...... 26 4.2.1 Overview ...... 26 4.2.2 Major Design Decision ...... 26 4.2.3 Technology Comparison ...... 27 4.2.3.1 Operating System ...... 27 4.2.3.2 Device ...... 29 4.2.3.3 Framework ...... 31 4.2.3.4 Runtime Environment ...... 34 4.2.4 Component Structure ...... 36 4.2.4.1 Service Interaction ...... 36 4.2.4.2 Service Logic ...... 37 4.2.4.3 Data ...... 37 4.2.4.4 Settings View ...... 37 D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 5 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.2.4.5 Extension View ...... 38 4.2.4.6 Sensor View ...... 38 4.2.4.7 Viki View ...... 38 4.2.4.8 Project View ...... 38 4.2.5 Interfaces ...... 39 4.2.5.1 SiMa Services ...... 39 4.2.5.2 Services ...... 40 4.2.6 Consumed Services ...... 50 4.2.7 Summary...... 50 4.3 Construction Operator Application ...... 51 4.3.1 Major Design Decision ...... 51 4.3.2 Technology Comparison ...... 51 4.3.2.1 Smart glasses ...... 51 4.3.2.2 Frameworks ...... 55 4.3.2.3 Augmented Reality Frameworks ...... 60 4.3.3 Component Structure ...... 62 4.3.3.1 Service Access ...... 62 4.3.3.2 Service Logic ...... 63 4.3.3.3 Service Data ...... 63 4.3.4 Interfaces ...... 64 4.3.5 Consumed Services ...... 64 4.3.6 Summary...... 64 4.4 Dashboard ...... 65 4.4.1 Overview ...... 65 4.4.2 Major Design Decision ...... 65 4.4.3 Technology Comparison ...... 65 4.4.3.1 Technology Selection ...... 68 4.4.4 Component Structure ...... 70 4.4.4.1 Data Tier ...... 70 4.4.4.2 Logic Tier ...... 71 4.4.4.3 UI Tier ...... 71 4.4.5 Interfaces ...... 72 4.4.6 Consumed Services ...... 72 4.4.7 Summary...... 72 4.5 Visual Wiki ...... 73 4.5.1 Overview ...... 73 4.5.2 Major Design Decision ...... 73 4.5.3 Technology Comparison ...... 73 4.5.3.1 Communication Frameworks ...... 73 4.5.3.2 Translation Frameworks ...... 77 4.5.4 Component Structure ...... 78
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 6 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.5.4.1 Service Access ...... 79 4.5.4.2 Service Logic ...... 79 4.5.4.3 Service Data ...... 80 4.5.5 Interfaces ...... 80 4.5.5.1 Get Execution Details Assets ...... 81 4.5.5.2 Get Execution Details Assets by UID...... 82 4.5.5.3 Modify Execution Details Assets ...... 83 4.5.5.4 Create a new Execution Details Assets ...... 84 4.5.5.5 Delete an Execution Details Assets ...... 85 4.5.5.6 Delete Execution Details Assets by UID ...... 86 4.5.5.7 Get Extended Visual Annotation ...... 87 4.5.5.8 Get Extended Visual Annotations by UID ...... 88 4.5.5.9 Get Translated Extended Visual Annotations ...... 90 4.5.5.10 Modify an Extended Visual Annotations ...... 91 4.5.5.11 Create an Extended Visual Annotation ...... 92 4.5.5.12 Delete an Extended Visual Annotation ...... 93 4.5.5.13 Delete Extended Visual Annotations by UID ...... 94 4.5.6 Consumed Services ...... 95 4.5.7 Summary...... 95 4.6 Sensor Abstraction Framework ...... 96 4.6.1 Overview ...... 96 4.6.2 Major Design Decision ...... 96 4.6.2.1 Platform and Devices ...... 96 4.6.2.2 Creation and Upkeep of Sensor Profiles on the PN ...... 97 4.6.2.3 Utilization of Sensor Plugins ...... 98 4.6.3 Technology Comparison ...... 98 4.6.3.1 Frameworks Comparison ...... 98 4.6.3.2 Plugin Architecture Comparison ...... 102 4.6.4 Component Structure ...... 105 4.6.4.1 Sensor Abstraction ...... 105 4.6.4.2 Framework Logic ...... 106 4.6.4.3 Access ...... 107 4.6.5 Interfaces ...... 107 4.6.5.1 Sensor Plugins ...... 107 4.6.5.2 Client Services ...... 113 4.6.6 Consumed Services ...... 116 4.6.6.1 Authorisation Services ...... 116 4.6.6.2 Profile Nexus Services ...... 117 D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 7 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.6.7 Summary...... 117 4.7 Autonomous Messaging Framework ...... 117 4.7.1 Overview ...... 118 4.7.2 Major Design Decisions ...... 118 4.7.3 Technology Comparison ...... 119 4.7.4 Technology Selection ...... 123 4.7.5 Component Structure ...... 124 4.7.6 Interfaces ...... 126 4.7.6.1 Gateways ...... 126 4.7.6.2 WebSocket Interface ...... 133 4.7.6.3 Service Registration and Discovery API ...... 134 4.7.6.4 Mappings and Transformations ...... 137 4.7.6.5 Workflows and activities ...... 140 4.7.6.6 Cloud Base Archiving ...... 142 4.7.7 Protocols and Data Formats ...... 143 4.7.7.1 Protocols ...... 143 4.7.7.2 Format ...... 144 4.7.8 Summary...... 146 4.8 Profile Nexus ...... 146 4.8.1 Overview ...... 146 4.8.1.1 Major Design Decisions ...... 147 4.8.1.2 Technology Comparison ...... 148 4.8.1.3 Technology Selection ...... 148 4.8.2 Information Data Model ...... 149 4.8.2.1 Overview ...... 149 4.8.2.2 Major Design Decision ...... 150 4.8.2.3 Theoretical Data Structure ...... 151 4.8.3 Construction Profile ...... 159 4.8.3.1 Overview ...... 159 4.8.3.2 Major Design Decision ...... 159 4.8.3.3 Technology Comparison ...... 160 4.8.3.4 Component Structure...... 163 4.8.3.5 Interfaces ...... 164 4.8.3.6 Consumed Services...... 166 4.8.4 Quality Profile ...... 166 4.8.4.1 Overview ...... 166 4.8.4.2 Interfaces ...... 166 4.8.4.3 Consumed Services...... 171 4.8.5 User Profile ...... 172
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 8 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.8.5.1 Overview ...... 172 4.8.5.2 Updating User Profile Data ...... 172 4.8.5.3 Retrieving User Profile Data ...... 173 4.8.5.4 Summary ...... 177 4.8.6 Workflow Profile ...... 177 4.8.6.1 Interface Get Crew...... 177 4.8.6.2 Interface Update Crew ...... 178 4.8.6.3 Interface Get Task ...... 179 4.8.6.4 Interface findMismatchedTasks ...... 181 4.8.6.5 Interface Update Task ...... 181 4.8.6.6 Interface Get Task Workflow ...... 183 4.8.6.7 Interface Update Task Workflow ...... 185 4.8.6.8 Interface Subscribe to Workflow Notifications ...... 186 4.8.6.9 Interface Subscribe to Workflow Control Reminders ...... 187 4.8.6.10 Interface Attach Report ...... 188 4.8.6.11 Summary ...... 189 4.9 Service Market Place ...... 189 4.9.1 Overview ...... 189 4.9.2 Major Design Decision ...... 190 4.9.3 Technology Comparison ...... 190 4.9.3.1 Technology Selection ...... 191 4.9.4 Component Structure ...... 192 4.9.4.1 Service Interaction ...... 192 4.9.4.2 Service Logic ...... 193 4.9.4.3 Data ...... 193 4.9.5 Interfaces ...... 193 4.9.5.1 Information of a Service ...... 193 4.9.5.2 Information of a Service by version ...... 195 4.9.5.3 List Of All Services...... 196 4.9.5.4 Update Existing Service ...... 198 4.9.5.5 Add New Service ...... 199 4.9.5.6 Get Binary of a Service ...... 200 4.9.5.7 Rate a Service ...... 201 4.9.6 Consumed Services ...... 201 4.9.7 Summary...... 202 4.10 Knowledge and Information Storage ...... 202 4.10.1 Overview ...... 202 4.10.2 Major Design Decisions ...... 202
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 9 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.3 Technology Comparison ...... 204 4.10.3.1 Backend-as-a-Service ...... 205 4.10.3.2 Documentation Framework ...... 206 4.10.3.3 Semi-Structured Data Storage Technologies ...... 208 4.10.3.4 Binary Data Storage Technologies ...... 210 4.10.4 Component Structure ...... 212 4.10.5 Interfaces ...... 213 4.10.5.1 RESTful Interfaces ...... 213 4.10.5.2 Java Interfaces ...... 226 4.10.6 Consumed Services ...... 234 4.10.7 Summary...... 235 5 Mockups ...... 236 5.1 Introduction ...... 236 5.2 Dashboard ...... 236 5.2.1 Login ...... 236 5.2.2 Home View ...... 237 5.2.3 Detail Alert View ...... 238 5.2.4 Alert Answer View ...... 239 5.3 SiMa App ...... 239 5.3.1 Settings Extension ...... 239 5.3.2 Marketplace Extension ...... 240 5.3.3 Sensor Extension ...... 241 5.3.4 Viki Extension ...... 242 5.4 CoOp App ...... 243 5.4.1 Login ...... 243 5.4.2 Main Screen ...... 244 5.4.3 Scan Screen ...... 244 5.4.4 My Tasks Screen ...... 245 5.4.5 Task Screen ...... 245 6 Conclusion and Next Steps ...... 247 7 Annex ...... 249
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 10 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
List of Figures, Tables and Listings
List of Figures
Figure 1: Statistic – EU5 – Mobile Market Share (Aug 2015)...... 28 Figure 2: Statistic – The Population of the EU5 compared to the Smart Phone Users ...... 30 Figure 3: UML Component Diagram – SiMa Service ...... 36 Figure 4: Vuzix M100 ...... 52 Figure 5: Epson Moverio BT200 ...... 53 Figure 6: Daqri Smart Helmet ...... 53 Figure 7: Microsoft Hololens ...... 54 Figure 8: UML Component Diagram – CoOp Components...... 62 Figure 9: Examples of Responsive Design of a Web Page...... 67 Figure 10: Dashboard Technology Comparison ...... 68 Figure 11: Stack of technologies ...... 69 Figure 12: UML Component Diagram - Dashboard ...... 70 Figure 13: UML Component Diagram – Viki Components ...... 79 Figure 14: Android Sensor Stack ...... 97 Figure 15: High-level Android Architecture and the Relationship between the Android NDK and SDK ...... 99 Figure 16: UML Component Diagram - SAF ...... 105 Figure 17: ESB (Enterprise Service Bus) technologies evaluation ...... 123 Figure 18. TIE Smart Bridge Architecture ...... 125 Figure 19 Architecture of the TIE E-Archiving Solution ...... 142 Figure 20: AMF Inter-Component Message ...... 145 Figure 21: AMF Queue Subscription Message ...... 145 Figure 22: AMF Topic Subscription Message ...... 146 Figure 23: AMF Queue Unsubscription Message ...... 146 Figure 24: AMF Topic Unsubscription Message ...... 146 Figure 25. Profile Nexus Overview ...... 147 Figure 26: Data Structure for the Creation of Task List, Component and Material Inventory ...... 151 Figure 27: Data Framework for Task, Components and Materials ...... 152 Figure 28: Data structure for the construction area ...... 153 Figure 29: Data Structure for the Definition of Crew, Timespan for a Work and Crew Assignment to a Task ...... 154 Figure 30: Data Structure for the Creation of a Task Workflow ...... 154 Figure 31: An Example of Workflow and its Actualization by Reporting Process in the Quality Profile ...... 155 Figure 32: Data Structure for Report List ...... 156 Figure 33: Data Structure of the Quality Profile ...... 157 Figure 34: Data Structure of the Construction Project Profile ...... 158 Figure 35: Data Structure of the Project User Profile ...... 159 Figure 36: Information Delivery Manual. Guide to Components and Development Methods’ by Building Smart ...... 162
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 11 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 37: Picture from ‘Information Delivery Manual. Guide to Components and Development Methods’ by Building Smart ...... 163 Figure 38: Construction Profile sub-components ...... 163 Figure 39: UML Component Diagram – Market Place Service ...... 192 Figure 40 : KIS Component Structure Diagram ...... 212 Figure 41: Dashboard Login ...... 237 Figure 42: Dashboard Home View ...... 238 Figure 43: Dashboard Detail Alert ...... 239 Figure 44: Dashboard Alert Answer ...... 239 Figure 45: SiMa Mock-Up - Settings Extension ...... 240 Figure 46: SiMa Mock-Up - Marketplace Extension ...... 241 Figure 47: SiMa Mock-Up - Sensor Extension ...... 242 Figure 48: SiMa Mock-Up – Viki Extension ...... 243 Figure 49: CoOpApp Login ...... 244 Figure 50: CoOpApp Main Screen ...... 244 Figure 51: CoOpApp Scan Screen ...... 245 Figure 52: CoOpApp MyTask Screen ...... 245 Figure 53: CoOpApp Task Screen ...... 246 List of Tables
Table 1: Dependencies between components ...... 19 Table 2: Generic Criteria ...... 25 Table 3: Comparison Criteria Operating System ...... 29 Table 4: Comparison Criteria Devices ...... 31 Table 5: Comparison Criteria Framework ...... 33 Table 6: Comparison Criteria Runtime Environment ...... 35 Table 7: Smart Glasses comparison ...... 55 Table 8: Frameworks Comparison ...... 59 Table 9: Augmented Reality comparison ...... 61 Table 10: Consumed Services ...... 64 Table 11: Services Consumed by Dashboard ...... 72 Table 12: Communication Frameworks Comparison ...... 76 Table 13: Translation Framework Comparison ...... 78 Table 14: GetEDA interface ...... 81 Table 15: GetEDAByUID interface ...... 82 Table 16: putEDA interface ...... 83 Table 17: PostEDA interface ...... 84 Table 18: DeleteEDA interface ...... 85 Table 19: DeleteEDAByUID interface ...... 86 Table 20: GetEVA interface ...... 87 Table 21: GetEVAByUID interface ...... 88 Table 22: GetTranslateEVA interface ...... 90 Table 23: PutEVA interface ...... 91 Table 24: PostEVA interface ...... 92 Table 25: DeleteEVA interface ...... 93 Table 26: DeleteEVAByUID interface ...... 94 Table 27: Frameworks Comparison ...... 101 D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 12 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 28: Plugin Architecture Comparison ...... 104 Table 29: RESTful Interface Description – Get a List of Queues and Topics...... 127 Table 30: RESTful Interface Description – Subscribe to a Queue or a Topic ...... 128 Table 31: RESTful Interface Description – Unsubscribe from a Queue or a Topic ...... 130 Table 32: RESTful Interface Description – Send a Message to a Queue or a Topic ...... 131 Table 33: RESTful Interface Description – Establish a WebSocket Connection ...... 133 Table 34: RESTful Interface Description – List Services...... 135 Table 35: RESTful Interface Description – Invoking a Service ...... 136 Table 36: RESTful Interface Description – Find Mappings ...... 138 Table 37: RESTful Interface Description – Upload Mapping ...... 139 Table 38: RESTful Interface Description – List Workflows ...... 140 Table 39: Construction Profile Technology Comparison ...... 161 Table 40: Provides3DModel Interface ...... 164 Table 41: GetDocument&Details Interface ...... 165 Table 42: Consumed Services by Construction Profile ...... 166 Table 43: RetrieveChecklist Interface ...... 167 Table 44: SearchChecklist Interface ...... 167 Table 45: PostChecklist Interface ...... 168 Table 46: RetrieveChecklist Interface ...... 169 Table 47: RetrieveSpecificMetric Interface ...... 170 Table 48: Consumed Services from KIS ...... 171 Table 49: Consumed Services from PN ...... 172 Table 50: Find Users Interface ...... 173 Table 51: List Users with an Access Right Interface ...... 174 Table 52: List Users with a Skill Interface ...... 175 Table 53: List Users with a Role Interface ...... 176 Table 54: Get Crew Interface ...... 177 Table 55: Update Crew Interface ...... 178 Table 56: Get Task Interface ...... 179 Table 57: Find Mismatched Tasks Interface ...... 181 Table 58: Update Task Interface ...... 181 Table 59: Get Task Workflow Interface ...... 183 Table 60: Update Task Workflow Interface ...... 185 Table 61: Subscribe to Workflow Notifications Interface ...... 187 Table 62: Subscribe to Workflow Control Reminders ...... 187 Table 63: Attach Report ...... 188 Table 64: SMP Technologies comparison ...... 191 Table 65: RESTful Interface Description – Information of a Service ...... 194 Table 66: RESTful Interface Description – Information of a Service by Version ...... 195 Table 67: RESTful Interface Description – List of all Services ...... 196 Table 68: RESTful Interface Description – Update a service ...... 198 Table 69: RESTful Interface Description – Add a service ...... 199 Table 70: RESTful Interface Description – Add a service ...... 200 Table 71: RESTful Interface Description – Rate a service ...... 201 Table 72: KIS - Shared Criteria for Technical Specification – Storage Technologies ...... 204 Table 73: Technology Comparison of BaaS-systems ...... 205 Table 74: Comparison of Documentation Frameworks ...... 207 Table 75: KIS - Comparison of Technologies for Semi-Structured Data Storage ...... 209 D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 13 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 76: KIS - Comparison of Technologies for Binary Data Storage ...... 211 Table 77: RESTful Interface Description – Common Return Codes ...... 213 Table 78: RESTful Interface Description – Create Bucket ...... 214 Table 79: RESTful Interface Description – Describe Bucket ...... 215 Table 80: RESTful Interface Description – Delete Bucket ...... 216 Table 81: RESTful Interface Description – Describe Bucket ...... 217 Table 82: RESTful Interface Description – Delete Bucket ...... 217 Table 83: RESTful Interface Description – Create Object(s) ...... 219 Table 84: RESTful Interface Description – Read Object ...... 220 Table 85: RESTful Interface Description – Update Object ...... 221 Table 86: RESTful Interface Description – Delete Object ...... 222 Table 87: RESTful Interface Description – Query Read ...... 222 Table 88: RESTful Interface Description – Query Delete ...... 225 Listings
Listing 1: Binding to the Service ...... 39 Listing 2: Send Message ...... 39 Listing 3: XML permission ...... 40 Listing 4: Format of an Update User Message ...... 173 Listing 5: Service Information ...... 194 Listing 6: App Information ...... 195 Listing 7: Service Information ...... 196 Listing 8: Service Information ...... 196 Listing 9: List of Services ...... 198 Listing 10: List of Services ...... 198 Listing 11: Update a service ...... 199 Listing 12: Insert a service ...... 200 Listing 13: Insert a service ...... 201 Listing 14: Insert a service ...... 201 Listing 15: Example – Converting a Java-Object to a JSON-Object...... 226 Listing 16: API Method Signature for Creating a Bucket and the Usage of this Method .. 227 Listing 17: API Method Signature for Listing Buckets and the Usage of this Method ...... 227 Listing 18:API Method Signature for Describing a Bucket and the Usage of this Method 228 Listing 19: API Method Signature for Deleting a Bucket and the Usage of the Method ... 229 Listing 20: Factory Method to Create a Test Data Object ...... 229 Listing 21: Operation createObject and the Usage of this Method ...... 230 Listing 22: Operation readDataObject and the Usage of this Method ...... 231 Listing 23: Operation updateObject and the Usage of this Method ...... 232 Listing 24: Operation deleteObject and the Usage of this Method ...... 232 Listing 25: API Method Signature to Execute a Generic Query on a Specific Bucket and the Usage of this Method ...... 234
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 14 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
1 Introduction ACCEPT – Assistant for Quality Check during Construction Execution Processes for Energy-efficienT buildings – is a project funded by the Horizon 2020 Framework Programme of the European Commission under Grant Agreement No. 636895. The ACCEPT system will run on Smart Glasses and unobtrusively guide workers during the construction on site. This provides a standardized and coordinated process for all workers, ensuring that all benefits of energy-efficient building components are maintained The ACCEPT system consists of three pillars: Advanced Knowledge Transfer for Energy-efficient Construction Agile Project Coordination for Bridging Heterogeneities Adaptive Quality Assurance with Self Inspection-Features 1.1 ACCEPT Project Overview One of the major problems in the construction sector today is the potential loss of benefits of energy-efficient building components because of the lack of knowledge or bad implementation during the construction processes. The outcomes of the ACCEPT project will help to overcome this problem with the following applications as a holistic platform: The Construction Operator Assistant App (CoOpApp) running on Smart Glasses, which passively collects data and actively provides guidance to the worker on site during the building process. (Pillar I: Advanced Knowledge Transfer for Energy- efficient Construction) A Site Manager App (SiMaApp) running on a mobile device, which allows to remotely coordinate the working process as well as collect additional data on site by different sensors. (Pillar II: Agile Project Coordination for Bridging Heterogeneity) An interactive web-based Dashboard as a monitoring and quality assurance solution. The Dashboard will use self-inspection methods to determine important characteristics such as U-Values. (Pillar III: Adaptive Quality Assurance with Self- Inspection Features) To achieve its goals, the project ACCEPT conducts original research from a user centred perspective and applies technologies from the fields of Ubiquitous Computing, Big Data, Cyber Physical Systems, the Internet of Services, and Human-Computer Interaction. For more information, please refer to the project website at http:/www.accept-project.com. 1.2 Deliverable Purpose, Scope and Context The purpose of the document is to specify the technical information of the ACCEPT System, with the purpose to be a guidance for the implementation of the system. This document provides deep information about ACCEPT components, technical details about different technologies to implement the components, its interaction to allow the exchange of information. To write this document we are using as a base the Architecture Definition and Functional Specification deliverable (Deliverable D2.7).
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 15 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The description in the document are low level and includes concrete technological selections to develop each component of the ACCEPT System. This level allows to know what are the more adequate tools to develop our system at this moment. 1.3 Document Status and Target Audience This document is listed in the Description-of-Action (DoA) as “public”, as it provides general information about the goals and scope of the ACCEPT project and can therefore be used by external parties in order to get according insight into the project activities. While the document mainly aims at the project’s contributing partners, this public deliverable can also be useful for the wider scientific and industrial community. This includes other publicly funded research and development projects, which may be interested in collaboration activities. 1.4 Abbreviations and Glossary A definition of common terms and roles related to the realization of the ACCEPT project as well as a list of abbreviations is available in the supplementary document “Supplement: Abbreviations and Glossary”, which is provided in addition to this deliverable. Further information can be found at http://www.accept-project.com. 1.5 Document Structure This deliverable is broken down into the following sections: Section 1 provides an introduction for this deliverable including a general overview of the project, and outlines the purpose, scope, context, status, and target audience of this deliverable. Section 2 provides an overview of the ACCEPT system, with a summary of the architecture, the different components and dependencies between them. Section 3 is about Major Design Principles in the ACCEPT system, talking about Security and Privacy, Data Formats, Communication and Interactions, Extensibility and Testing. Section 4 is the most important section of the document because is about technical specification of all ACCEPT components. This section show in deep each component and its interaction with the other components of the ACCEPT system. Section 5 shows the different mockups of the User Interface tools of our system: Dashboard, SiMaApp and CoOpApp. Finally, section 6 includes conclusions and next steps.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 16 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
2 System Overview This section consists of a brief summary of the ACCEPT system, considering its architecture, its components and the existing dependencies between them 2.1 Architecture The ACCEPT architecture is composed by three different architecture layers: a FrontEnd, a BackEnd and a Storage layer: The FrontEnd layer is composed by three components that can be accessed by the users: o Site Manager App is a mobile application. By using this application, users can improve their work in a building construction. More details about this component are shown in section 4.2. o Construction Operator App is a smart glasses application. It is unobtrusive fort the users and allows them to visualize information regarding the construction, and providing guidance to the worker on real time during the building process. This component is more detailed in section 4.3. o Dashboard is a web client for the ACCEPT System. The main goal of Dashboard is to provide a high-level view on the Quality aspects of the building and the construction process. In addition, users are able to add new Execution Details Assets in the Dashboard. For more information about this component, see section 4.4. The BackEnd layer is composed by the following components: Visual Wiki (section 4.5), Sensor Abstraction Framework (section 4.6), Autonomous Messaging Framework (section 4.7), Profile Nexus (section 4.8) and Service Market Place (section 4.9). These components allow the information exchange process in the ACCEPT system. They work as a black box which executes all the system processes. The Storage layer is mainly composed by the Knowledge Information Storage (KIS) component. KIS is necessary for the privacy-aware data management in the ACCEPT system. Project data will be stored in “buckets”. These small data storage units can be used to store data isolated from each other based on the origin. This principle allows a good data privacy management as it enforces KIS clients to access data only in a specific bucket. It is known as a sandbox in other ICT domains. This component is shown in section 4.10. 2.2 Components This subsection introduces the different ACCEPT system components. They were fully described in D2.7 Architecture Definition and Functional Specification. The Site Manager Application (SiMaApp) is the app for a mobile device of the Google Project Tango and will be used to check the progression of a construction site, as well as to manage the day-to-day work. It offers a unified access point to the functionality of the distributed server components of the ACCEPT system. It
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 17 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
provides Interfaces and the Runtime for ACCEPT extensions as well as handling all communication between the ACCEPT extensions and the SAF Constructor Operator Application (CoOpApp) is the component in charge of managing the smart glasses. This component allow the users to add Extended Visual Annotations (EVA) into any part of a construction site by Augmented Reality technology, to view instructions as videos or images about how to do something in the construction(e.g. how to install a window) and also to take pictures and send them to the ACCEPT system. It runs on Epson Moverio BT-200 smart glasses and they offer Augmented Reality (AR) information, as Executed Details Assets (EDA) and Extended Visual Annotations (EVA) objects Dashboard is a web client for the ACCEPT System developed with the Dart framework and it is used mainly as a desktop client. The main goal of the Dashboard is to provide a high-level view on the Quality aspects of the building and the construction process. Users are able to select different metrics they is interested in. Every time a user logs in the Dashboard, he/she is able to see, at a glance, the quality status of these different metrics and to browse the Quality metrics, from the high level view to more detailed ones. By this way the user can know the needed priority about different quality aspects of the construction process. In addition, a user can add new Execution Details Assets from the Dashboard. Visual Wiki (Viki) is the component responsible for managing information about Augmented Reality (AR), sending AR information as 3D Models and Virtual Notes to the users. Viki exposes REST interfaces that provide different services for the managing and interaction with AR information types EDA and EVA. It also offers translation of EVA through different API’s. The Sensor Abstraction Framework (SAF) encapsulates the logic for managing all aspects of sensors and defines how these sensors can feed the data to the system. It is located on the client (SiMaApp & CoOpApp) devices, and communicates with the Profile Nexus (PN), to archive its sensor readings, and the Authorisation Component, to authorise client actions. SAF is developed with the Android SDK. The Autonomous Messaging Framework (AMF) provides an easy to use infrastructure for any interaction of all components of the ACCEPT system. AMF is a conduit that tires up together all participants of the ACCEPT system from legacy data sources and business services to users interacting with the system via hand- held devices AMF is developed with the TIE Smart Bridge solution that is a commercial product of one of the project partners. Profile Nexus (PN) is the component that manages the information related to the construction activity of the ACCEPT system. (BIM, roles, workflow, technical documentation, etc.). It is provides different services for the interaction with the four profile types: Construction Profile, Quality Profile, Project Workflow Profile and User Profile. It provides the business logic that allows the interaction between profiles in an event-driven environment. The Service Market Place is a server application and repository for third party services. The SMP allows users to add specific functionalities not incorporated in the default features of the ACCEPT System. The Knowledge and Information Storage (KIS) component is an abstraction of all required databases in the ACCEPT system. It enables the other components to
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 18 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
store any data securely in an easy to use manner. For this purpose, it offers different RESTful and Java interfaces to the ACCEPT System.
2.3 Dependencies between Components This subsection shows an overview of the dependencies between all ACCEPT components. Section 4 shows the services or interfaces the components use to connect to each other. For this purpose, the following table shows a summary about the dependencies. Table 1: Dependencies between components SiMa CoOp Dashboard Viki SAF AMF PN SMP KIS
SiMa ✔ ✔ ✔ ✔ ✔
CoOp ✔ ✔ ✔ ✔
Dashboard ✔ ✔ ✔ ✔
Viki ✔ ✔ ✔ ✔ ✔ ✔
SAF ✔
AMF
PN ✔ ✔
SMP ✔ ✔ KIS
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 19 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
3 Major Design Principles
3.1 Security and Privacy Two key aspects are especially important for technology uptake among the users of the ACCEPT system: security, guaranteeing the protection of personal and project data, and control, assuring that the users can influence how the data they are responsible for may be used. In terms of the technical specification of the ACCEPT system, the security and privacy related requirements can be broken down into the following aspects: Privacy settings in the end-user front-end Access control within components Security in web-based inter-component communication The first aspect deals with how privacy settings are managed and controlled by the end user. Secondly, access control within components will ensure that personal information stored by a component will not leak to other ACCEPT users/components or to 3rd parties, unless explicitly configured to allow external access. In ACCEPT, this requirement primarily applies to the Profile Nexus, the Visual Wiki and the Knowledge and Information Storage Finally, the ACCEPT system also uses web-based communication in the form of RESTful interfaces to provide services to other components. This communication needs to be safe and secure, so that personal information cannot be leaked by intrusive requests or eavesdropping. This means that all RESTful services must to be secure and adopt authentication mechanism. Below are the mechanisms that ACCEPT will adopt to fulfil these two requirements: Security: The communication between client and server side could be done across an untrusted network where the data could be leaked. In order to avoid this situation, the communication will be secured adopting the Transfer Layer Protocol (TLS), which ensures an encrypted communication between authenticated communication partners. This security method is also used in HTTPS. Authorisation: Once the communication is secure, the user of a web service has to be authenticated. For this a dedicated component will be used, whereas the authorisation should be handled by each component on its own. There will be a central component, which will direct queries regarding the authorisation to the component concerned. 3.2 Data Formats Technologies which provide a certain degree of interoperability is preferred so ACCEPT system will work by standardized and open data formats. The key factors in the decision-making have been: How is it planned to analyse, sort, or store What formats are well developed for interoperability D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 20 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
What formats are compatible with hardware used in the system What formats are at risk of obsolescence, because of new versions or their dependence on particular software Formats admitted in the work area Poor software interoperability has long been regarded as an obstacle to industry efficiency in general and to BIM adoption in particular where exchanging data is something necessary. BIM is often associated with Industry Foundation Classes (IFCs) – data structures for representing information. IFC format have been developed by buildingSMART (the former International Alliance for Interoperability), as a neutral, non- proprietary or open standard for sharing BIM data among different software applications (some proprietary data structures have been developed by CAD vendors incorporating BIM into their software). The IFC model specification is open and available. It has been registered by ISO and it is an official International Standard ISO 16739:2013. So the IFC file format could be taken as a good example of data format which has all the conditions to be implemented into ACCEPT system. 3.3 Communication and Interaction Properties of the enterprise application integration include: a lot of data being exchanged, diversity of formats, data accessed concurrently with high speed, plenty of different user interfaces/GUIs, requires integration with other enterprise systems. Communication types: shared database and messaging. At the system/architectural level integration among components will be organised through messaging, with common participants being KIS and PN. Messaging system will be organised essentially as a set of pipelines that support high level of decoupling between communicating actors (special, temporal, functional) that relay events (in form of messages) between senders and receivers. Messaging should follow a “dump-pipeline – smart end point” principle to support scalability and availability. Events have to have topics to which receivers can be subscribed. Types of domain events should be defined following open-closed principle, i.e. the set of topics/event types can be extended but existing topics cannot be removed or changed. Integration will support RESTful style via HTTP(s), WebSockets, and integration with legacy systems via Autonomous Messaging Framework that glues together all those integration paradigms, performs monitoring, e-archiving of messages, workflows execution, message transformations and protocol adaptation. Functionality for cross-cutting concerns such as security could be applied at the levels of communication modules, and messaging infrastructure in orthogonal manner to all messaging that can include, for instance, encoding of messages, signing, transferring through the protected channels (e.g., point-to-point VPN should be the ultimate solution in this respect). 3.4 Extensibility It is a requirement for any long-term development project to anticipate the future and to think in terms of extensibility, so that future functionalities or modules can easily be
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 21 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
integrated. This section details the different extensibility mechanisms that have been put in place within the ACCEPT project.
3.4.1 Back-end Extensibility The architecture of the back-end has been designed to be extensible. Here are the many extensibility elements of its architecture: Autonomous Messaging Framework (AMF): This module provides an independent representation of the different messages exchanged in the system. The AMF standardize the communication between all modules. Therefore, the technical decisions for each module do not impact other modules, the only requirement for a module is to respect the AMF message format. It makes the addition of new modules much easier, as they only have to understand the AMF communication mechanism. Profile Nexus: Is a module where complex domain-oriented activities are represented (BIM, people, workflow, quality). This provides a useful ‘encapsulation’ strategy to hide part of this complexity. It also provides an extensibility mechanism, because existing profiles can be extended, and new profiles can be added. Sensor Abstraction Layer (SAL): This layer has been added for abstracting the sensors to the other modules. Thus, it enables the addition of a new sensor in a uniform way to all modules. Different modules will import documents from external sources. For example, the workflow should be imported from an MS-Project file. In the context of this prototype, the number of such external file formats will be limited. In the future, it will be quite straightforward to support more data formats, based on the commercial deployment needs.
3.4.2 Client Extensibility Three different clients will be developed for ACCEPT. This shows that the back-end is already designed to support many different client applications. The clients themselves are extensible by design: they all are based on the notion of “extensions” (or “widgets”). A widget is a software component addressing a specific task. The client applications are all designed so that such widgets can easily be added.
3.4.3 Market Place Extensibility The market place offers a service comparable to the well-known Apple AppStore (or Google Play) that are available for smart devices. The goal of the market place is to centralize all possible extensions for the client applications, and let the user search and install these extensions. 3.5 Testing Testing is the process of evaluating a system or its components with the intent to find whether it satisfies the specified requirements or not. Testing is executing a system in order to identify any gaps, errors, or missing requirements in contrary to the actual requirements.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 22 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The following roles are involved in testing a system within their respective capacities: Software Tester, Software Developer, Project Lead/Manager and End User. Early testing reduces the cost and time to rework and produce error-free software that is delivered to the client. However, in Software Development Life Cycle (SDLC), testing can be started from the Requirements Gathering phase and continued until the deployment of the software. It also depends on the development model that is being used. Testing is done in different forms at every phase of SDLC: During the Requirement Gathering phase, the analysis and verification of requirements are also considered as testing. Reviewing the design in the design phase with the intent to improve the design is also considered as testing. Testing performed by a developer at the completion of the code is also categorised as testing. It is difficult to determine when to stop testing, as testing is a never-ending process and no one can claim that software is 100% tested. There are many techniques of testing. One of the most famous is “Black-Box testing”. The technique of testing without having any knowledge of how the system or application internally works is called black-box testing. The tester is oblivious to the system architecture and does not have access to the source code. Typically, while performing a black-box test, a tester will interact with the system's user interface by providing inputs and examining outputs without knowing how and where the inputs are being used. “Functional testing” is a specific type of black-box testing based on specifications of the software to be tested. The applications are tested by providing input and then the results are examined to conform if it works accordingly to the functionality it was intended for. Functional software testing is conducted on a complete, integrated system in order to evaluate the system's compliance with its specified requirements. Another testing technique is Unit Testing. This type of testing is performed by developers before the setup is handed over to the testing team to formally execute the test cases. Unit testing is performed by the respective developers on the individual units of source code assigned areas. Developers use different test data set to those used by the quality assurance team. The main goal of Unit testing is to isolate each part of the program and show that individual parts are correct in terms of requirements and functionality.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 23 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4 Technical Specification
4.1 Overall This subsection 4.1 presents a description about the structure format of the next subsections (4.2 to 4.10). All of the subsections m present a standard structure composed of the following points: an overview, major design decision, technology comparison (including technology selection reasons), component structure, interfaces, consumed services and a summary.
4.1.1 Overview The overview describes briefly every ACCEPT component, i.e. what is it and what it is going to provide to the rest of the System. It also contains a summary of the component.
4.1.2 Major Design Decision The Major Design Decision shows the technical specification highlights and the major design decisions for implementing a component. This subsection is useful for better understanding the technology comparison and selection.
4.1.3 Technology Comparison It consists on a technology comparison applicable to each component of the ACCEPT System. It presents the technologies and software APIs or frameworks that are useful for developing of the component, for the subsequent selection. The options are presented in a brief summary and it is focused in their benefits and disadvantages for the ACCEPT system. To compare the different tools, it is useful to use a table as the following one with some generic criteria.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 24 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 2: Generic Criteria
Parameter Description Generic Parameters Maturity & Stability & Quality Selecting a stable and mature solution may be one of the key criteria for some components of ACCEPT for ensuring a usable implementation of the ACCEPT Platform. However, for other components using cutting edge technologies may be more relevant. A good quality is required for any technology that is selected as a base for components
Extensibility As a potential alternative to a good quality open source solution, a technology with well-defined extendibility may be considered, e.g. in terms of plugin mechanisms
Open Source & Standards Even if an existing technology may be used as a base for a component, it is very likely that the technology needs to be extended or changed in order to meet all project requirements. As a consequence, open source solutions are likely to be preferred by the consortium, although in certain circumstances off-the-shelf solutions can be of preference (e.g. due to a partner’s commercial expertise, the technology is not the focal RTD, or it is not the market reality). Whenever an open standard exists, solutions should be preferred as long as those standards are openly accessible and applicable. The main constraint to standards compliance is that they have to be real world standards (defacto or dejure), that they are actually used in the market and that do not hinder the technical up-to-datedness as described above
Familiarity / Support / For clarifying questions and discussing possible problems of a technology, a Community strong community should be available.
Performance / Scalability Performance is an important criterion for all core components of ACCEPT although the meaning of “performance” might differ from component to component
State of the Art In which level of development is the technology (technologies, devices or scientific fields) now, it has been used in other solutions or projects
EU Project Origin Bearing in mind the origin of ACCEPT in the EU FP programmes its leading- edge nature, solutions by other EU RTD projects can be quite useful in the context of a project although the juxtaposition is that most likely these technologies may not be mature or market accepted. However, in general this criterion does not have a high priority compared to others
Licenses Technologies with free licenses should be preferred, but if the development of a component is more expensive with a free tool that paying a license, then we prefer the technology with license.
4.1.3.1 Technology Selection Inside the technology comparison, a brief discussion about the motivation of selecting the specific technology is given.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 25 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.1.4 Component Structure This is a more detailed structure of each ACCEPT component than the previously given in the document D2.7 Architecture Definition and Functional Specification. It includes an explanation of all the subcomponents of the component and about its functionality. In this section the technology selection can also be taken into consideration.
4.1.5 Interfaces The interfaces provided for each component of the ACCEPT System to collaborate and communicate each other are described here. For this purpose, declarations of methods and services offered by the component will be described.
4.1.6 Consumed Services Consumed services will describe the services offered by other ACCEPT components who are going to be used by the component in concern.
4.1.7 Summary Finally, a summary about the component technical specification is offered. It will explain the most important decision taken over each component of the ACCEPT System. 4.2 Site Manager Application
4.2.1 Overview The Site Manager App (SiMaApp) offers a unified access point to the functionality of the distributed server components of the ACCEPT System. It provides Interfaces and the Runtime for ACCEPT extensions as well as handling all communication between the ACCEPT extensions and the SAF (Sensor Abstraction Framework). The SiMaApp provides API Wrappers for all other ACCEPT components. API Wrappers offers an access point to the Authorisation Manager, so that apps need special permissions to access these components.
4.2.2 Major Design Decision According to the Functional and Global Architecture, the following decisions have been made: Device Aspects Rather obvious, the device of the SiMaApp has to be a mobile device. The proper device has to be selected, which is state of the art and should be future-proof. So that the client can be still used on new devices after years. Further, it should be possible to install new sensors and access them for the SAF. Inter-App Communication
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 26 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
For the components to communicate with each other, an approach has to be chosen which allows a rapid implementation and a state of the art way of internal messaging. It should be extensible, and should provide a reliable way of bi-directional communication. Security Since the SiMaApp has access to sensitive data, either directly or indirectly, it has to ensure that only extensions with the necessary rights will be able to access sensitive information. Furthermore, only user having the necessary access rights to the system will be able to access specific data or do specific tasks.
4.2.3 Technology Comparison
4.2.3.1 Operating System The operating system is one of the most important choices regarding the Application Runtime Environment, since there are many requirements to the runtime itself. It should at least run on mobile devices. It should be state of the art, updated on a regular base, open for hardware access to make use of internal and external sensors and outputs like the audio device. The chosen operating system of the device should be widely available to reach the highest possible customer range. It should further be extensible, and it should be possible to modify the system according to user requirements. Android, the most used mobile device operating system was developed by the “Open Handset Alliance” under the lead of Google Inc.. It is a mobile operating system based on the Linux Kernel. It is designed primarily for smartphones and tablets. However, user interfaces for cars, televisions and watches are currently being developed or already available. Android is licensed under the Apache 2.0 license. The main programming languages are C++ and Java which could be run on multiple devices. iOS developed by Apple Inc. is exclusively distributed across Apple hardware and takes the second spot in the mobile device market share. It features a locked down eco system and a wide range of apps available through the app store. iOS is licensed under a proprietary EULA and not open sourced. The main programming language is Objectve-C, which is highly specialised to the Apple eco system. Windows Phone, currently being developed by Microsoft Corp., is the successor of Windows Mobile Phone. It features an easy to recognize start screen, consisting of so called “live tiles”, which show context sensitive information and allow the user to trigger actions. As iOS, Windows Phone is licensed under a proprietary EULA and does not allow modifications to the core. C# and C++ are the main languages for the development of Windows Phone Apps. But Microsoft announced to support Java and Objective-C in the future as well1.
1 https://en.wikipedia.org/wiki/Windows_10_Mobile D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 27 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Other
Windows
iOS
Android
01020304050607080
Figure 1: Statistic – EU5 – Mobile Market Share (Aug 2015)2
To compare the different technologies it uses the next specific parameters: Market Share: The market share is rather important, since it describes the user acceptance of a system. If a system is used by many people, they are already familiar with it and need less time to learn it. It also indicates how future proof a technology is, since a big contender would not disappear so quick from the market. Development Share: Since the system should be extensible by third party developers, it is important, that the technology is widely spread. So more developers are able to provide the extensions. It means as well, that it is more familiar for the developers of the developing partner.
2 http://www.kantarworldpanel.com/global/smartphone-os-market-share/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 28 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 3: Comparison Criteria Operating System
Parameter Importance Android iOS Windows Phone
Maturity & Stability & Quality +++ +++ +++ +++
Extensibility +/- +++ ++ +++
Open Source & Standards ++ +++ + ++
Familiarity / Support / Community +++ ++ + +++
Performance / Scalability +++ + ++ ++
State of the Art ++ +++ ++ +
EU Project Origin - - - -
Licenses ++ ++ o +
Specific Parameters Market Share +++ +++ + +
Development Share + ++ o +
4.2.3.1.1 Technology Selection According to the statistic by Kantar World Panel, the highest market share of mobile operating systems is taken by the Android platform, which is one of the important reasons to choose Android. For that reason, it should be more future-proof and more users know how such a device works, which will increase the acceptance of the target market. Another reason is the more commonly known programming language Java instead of the highly specialized programming language Objective-C, which is mandatory for the most prominent Android contender, the iOS platform.
4.2.3.2 Device The device is the system where the SiMaApp will be mainly developed on. It will be easy to adapt to a different mobile device, nevertheless minor changes are expected. For example many devices use different sensors (some have temperature build in), some have a better camera, different screen sizes with a different solution, a more up to date Operating system, a faster CPU, an unit to display 3D objects and much more. To make a decision, a choice has to be made about the general type of the device:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 29 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Smart phones are used by many people in Europe. In the UK for example live about 63 million people3 and about 40 million of them are smart phone users and it is still increasing4. The main contender in that category are Android phones. Tablets are very similar in the usability to Android smart phones. They are not spread as wide as smart phones, by far. Nevertheless tablets have the advantage to have a larger screen, so it is possible to show more information in a less confusing manner. Furthermore, the performance is better, since the manufacturers have more space available and can target for performance instead of size. Google Project Tango5 is a smartphone and tablet project by Google’s Advanced Technology and Projects group (ATAP), formerly a division of Motorola. The Tango device consists of many sensors, for example a motion tracking camera and a depth sensor. Those sensors may be used to detect the tablets orientation and what is in front of it, using that data to build out a 3D map of its surroundings.
90
80
70
60
50
40 Millions
30
20
10
0 France Germany Italy Spain UK
Smart Phone Users Population
Figure 2: Statistic – The Population6 of the EU5 compared to the Smart Phone Users7 To compare these technologies, it uses the next specific parameters: Usability: Performance of a device will help with the workflow and increase the usability of the ACCEPT devices. Another important factor is the screen size. Since a larger screen size means, that more details could be shown in a much cleaner way, the user will have a better oversight, which will improve the usability and the speed of working with the device.
3 https://en.wikipedia.org/wiki/Demography_of_the_United_Kingdom 4 http://dazeinfo.com/2014/12/18/worldwide-smartphone-users-2014-2018-forecast-india-china-usa-report/ 5 https://www.google.com/atap/project-tango/hardware/ 6 https://en.wikipedia.org/wiki/Demographics_of_Europe 7 http://dazeinfo.com/2014/12/18/worldwide-smartphone-users-2014-2018-forecast-india-china-usa-report/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 30 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Integrated Sensors: Integrated sensors will provide sensor data on every device. So those sensors do not need to be carried on itself as well and cannot be forgotten as well, since they are there all the time. Table 4: Comparison Criteria Devices
Parameter Importance Smart Phone Tablet Google Maturity & Stability & Quality +++ +++ +++ +++
Extensibility +/- +++ +++ +++
Open Source & Standards ++ +++ +++ +++
Familiarity / Support / Community +++ ++ ++ ++
Performance / Scalability +++ +++ +++ +++
State of the Art ++ ++ ++ +++
EU Project Origin - - - -
Licenses ++ --
Specific Parameters Usability +++ + ++ ++
Integrated Sensors ++ + + +++
4.2.3.2.1 Technology Selection
Since the usability of Android devices is very similar, the acceptance rate of Android tablets and smart phones should be very similar too. The larger screen size and better performance is an advantage for the tablets. And especially Google Project Tango has all the advantages of a tablet. Further, it includes some advanced sensors, which could become very handy. So the best fit for the ACCEPT project seems to be Google Project Tango.
4.2.3.3 Framework The Framework will decide about the programming languages, which will be used. Further it will have a minor influence on the architecture, which should be avoided but it is just possible to a certain degree. The SiMaApp must be able to execute and supervise Android apps, while being itself an Android app. As basis a framework has to be selected which allows such functionalities. The possibilities include the Android Application Framework or one of several cross-platform development frameworks allowing hardware resources access.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 31 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Android Application Framework8 is a set of APIs that allows developers to quickly and easily create apps for Android devices with the help of the Java programming language. It contains tools for designing User Interfaces and a documentation for the API. Essentially an Android app consists of activities (programs that the user interacts with), services (programs that run in the background or provide some function to other apps), and broadcast receivers (programs that catch information important for an app). The NDK9 is a toolset that allows to implement parts of Android applications using native-code languages such as C and C++. Typically, good use cases for the NDK are CPU-intensive applications such as game engines, signal processing, and physics simulation. The written parts of the program can be compiled to ARM, MIPS or the x86 processor architecture. They can be called from the Android Application Framework. Xamarin.Mobile10 is a library that exposes a single set of APIs for accessing common mobile device functionality across the iOS, Android, and Windows Phone platforms. This increases the amount of code developers can share across mobile platforms, making mobile app development more productive. Xamarin.Mobile currently abstracts the contacts, camera, and geo-location APIs across iOS, Android and Windows Phone platforms. Future plans include notifications and accelerometer services. It is based on Mono11 and uses C#, so developers can reuse existing .NET Framework libraries that are successfully ported to the Mono Framework. Rhodes is a development framework that lets software developers write software for mobile and desktop devices using a mixture of JavaScript, HTML5 and Ruby, instead of device specific languages. It is not a native approach. Instead a native application host a web view rendering the actual app. The PhoneGap Framework12 or Apache Cordova13 are mobile development frameworks which enable software developers to build apps for mobile devices using web technologies like JavaScript, HTML5 and CSS3, instead of device- specific languages. The resulting apps are hybrid, meaning that they are neither truly native (because all layout rendering is done via web views instead of the platform's native UI framework) nor purely web-based (because they are not just web apps, but are packaged as apps for distribution and have access to native device APIs as well as components written for the Android Application Framework). Mixing native and hybrid code snippets has been possible since version 1.9. The differences are just minor between the both frameworks, since PhoneGap wraps Apache Cordova. JXcore14 is a fork of Node.js and runs on multiple devices. Currently Android, iOS, Linux and Windows are supported and the Windows Phone support is planned in
8 http://developer.android.com/guide/faq/framework.html 9 http://developer.android.com/tools/sdk/ndk/index.html 10 http://xamarin.com/mobileapi 11 http://www.mono-project.com/Main_Page 12 http://phonegap.com 13 https://cordova.apache.org 14 http://jxcore.com D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 32 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
the near future. It allows to use Javascript as the programming language. Google’s V8 can be used to compile the JavaScript code so that the result is a native app. To compare these frameworks it uses the next specific parameters: Nativeness: Certain frameworks are closer to the system and provide more direct access to the system, than other frameworks. Therefore, it is possible to do more with the device, than with other frameworks. App Complexity: While certain frameworks provide more functionality and are easier to work with, the app complexity will be less, because of that. Therefore, the productivity will be increased, if the developer does not have to implement some commonly used functions, since they are not provided by the framework. The maintenance will be easier as well. Framework Compatibility: Some frameworks can be used by others. This is not so important, it just makes an option to use a framework as well in another one. The deciding factor here is, if a framework could use programs or libraries written in different frameworks. Therefore, it is possible to develop certain aspects in a framework, which is more suitable for the problem. Table 5: Comparison Criteria Framework
Parameter Importance AAF NDK Xamarin.Mobile Rhodes PhoneGap JXcore Maturity & Stability & +++ +++ +++ ++ + + + Quality
Extensibility +/- +++ + ++ ++ ++ ++
Open Source & ++ +++ ++ o +++ +++ +++ Standards
Familiarity / Support / +++ +++ + + ++ ++ ++ Community
Performance / +++ ++ +++ + + + + Scalability State of the Art ++ ++ ++ ++ +++ +++ +++
EU Project Origin ------
Licenses ++ -- -
Specific Parameters Nativeness ++ ++ +++ + + + +
App Complexity +++ +++ + +++ +++ +++ +++
Framework ++ +++ + ++ ++ ++ ++ Compatibility
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 33 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.2.3.3.1 Technology Selection The Android Application Framework seems to be the best choice for the SiMaApp. It is really powerful and if something could not be done, it is possible to use components build on the NDK. The NDK allows more control of the device but it increases the app complexity as well and slows down the productivity15. The main advantage of Apache Cordova and Rhodes is, to use web technologies for the UI, which results in less time spent on developing the UI. Further, the solutions are cross platform compatible. Since the SiMaApp will definitely run on Android and Android seems to be more future-proof than the frameworks like Cordova or Rhodes and most of the programming in the SiMaApp service will be in the backend and not the UI, the Android Application Framework is the better choice. Nevertheless SiMa extensions could use for example Apache Cordova, since the architecture will be developed in that way. As a piggy-back technology selection, Java is chosen as programming language, since apps developed with the Android Application Framework have to be developed in Java.
4.2.3.4 Runtime Environment The SiMaApp will rely on third party apps, which will provide additional benefit to the end user. To achieve this, the SiMa service needs to define a runtime environment which can handle generic third party apps. Furthermore, it has to ensure a seamless interaction between all components of the ACCEPT system. Compiling Android: Android is an Open Source Operating System, which can be compiled on a Linux based build environment. This allows to create an own adjusted Android operating system (ACCEPT OS). This would allow for example the denial to install non-ACCEPT apps. An ACCEPT app would require a special signature, so that the ACCEPT OS would determine, if an app is a legit ACCEPT app. The SiMa Service would be an integral part of the ACCEPT OS. An update to the SiMa Service would require a firmware-like update, which would need additional effort. Java Reflection: Using reflection, would allow loading generic Java components into the SiMa Service Appdomain. In order to use this approach every ACCEPT app would be needed to be deindexed. Furthermore, a special mechanism to load additional resources (like images, manifests, etc.) has to be developed. Standalone Apps/Inter-process Communication: The runtime environment could be a combination of a simple Android app and services. A central Android service could offer communication functionality for ACCEPT apps enabling the communication with other ACCEPT apps and ACCEPT components. An ACCEPT app would be a “normal” Android app consuming this special service. The service would control all interactions while enabling them to participate in the ACCEPT platform. To compare the runtime environment it uses the next specific parameters: Usability: Usability means, the effort a user has to learn the way of doing different things in the system.
15 http://developer.android.com/tools/sdk/ndk/index.html D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 34 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Effort: The effort means, how much effort is needed to implement the mentioned solution. Less time spent means that more time could be invested to other functionalities. Distribution channels: The possibility to reach more users is quiet important for involving third party developers. If more people could be reached, more third party solutions are provided. Therefore, the system has more abilities and get more interesting to customers. Table 6: Comparison Criteria Runtime Environment
Parameter Importance ACCEPT OS Reflection IPC Maturity & Stability & Quality +++ ++ ++ ++
Extensibility +/- + ++ +++
Open Source & Standards ++ +++ +++ +++
Familiarity / Support / Community +++ - ++ ++
Performance / Scalability +++ +++ ++ +++
State of the Art ++ + ++ ++
EU Project Origin - - - -
Licenses --
Specific Usability +++ ++ +++
Effort + +++ +++
Distribution Channels + + ++
4.2.3.4.1 Technology Selection The standalone approach has been chosen. It provides the overall best solution in terms of usability, stability and effort. Furthermore, the standard deployment routines Android offers could be used allowing more distribution channels. Later on, it is still possible to make an ACCEPT OS and use the developed service with some adaptions.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 35 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.2.4 Component Structure
Figure 3: UML Component Diagram – SiMa Service
4.2.4.1 Service Interaction First, there is the Interaction tier, which is used by third party extensions and extensions to communicate with the service and the ACCEPT system. No other component of the service is accessible from the outside. The only task for the Interaction layer is to forward the requests to the Service logic layer and send the responses back. Therefore, if there are any changes to the general logic of the component, the Interaction layer does not have to be changed. Similarly, a change in the Interaction layer does not require the change of
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 36 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
several components in the Service functionality. A detailed specification of this layer can be found in section 4.2.4.1.
4.2.4.2 Service Logic The logic of the Service is on the second layer. Here every decision and computation is done and it contains the general functionality of the Service. There are multiple components in it, which solve different problems: The Extension Controller provides the functionality of the Service to the interaction layer. It handles the coordination of the Service Logic and uses the other components of the Service Logic to communicate to ACCEPT modules, for deploying tasks and for the authentication respectively the authorisation. The Extension Deployment Manager handles everything, which has to do with the deployment of extensions. It handles things like the installation, uninstallation of extensions as well as the registration of extensions to the Service. The Extension Notification handles notifications of different extensions. If a change happens in ACCEPT and an extension wants to get notified of any changes on a specific item, this module handles it and notifies all extensions, which are observing that item. The Extension Registry is used to register each extension, which want to interact with the SiMa Service. Only Extensions, registered here, will be able to use most of the SiMa Service functions. To register an Extension, the action from section 4.2.5.2.6.1 has to be used. The Viki Manager is there to interact with the Viki informations. It loads and saves the EVA/EDA informations to the specific component. The Profile Manager interacts with the profile informations. The Access Manager handles everything concerning the authorisation and authentication in the Service. It will be used to check if a specific user is authorised to do certain actions in the service. For example, it ensures that a user can only use specific extensions. Therefore, it is possible to restrict every user in the use of their extensions. In addition, it will authenticate the user for other ACCEPT components. Finally, the Sensor Manager handles the communication to the SAL. It is also responsible for connecting and disconnecting different sensors.
4.2.4.3 Data The Data layer of the Service provides an interface to the Security functions like Authorisation and Authentication. Furthermore, the ACCEPT Model is responsible for accessing other ACCEPT components like the Profile Nexus, the Visual Wiki, the Service Market Place or the Sensor Abstraction Framework and provide the authentication to those components.
4.2.4.4 Settings View Additionally a settings view for the SiMaApp Service is foreseen as a separate app. It will be designed with the default Android graphic components and text system. It will allow the modification of all settings and will also be the basis for the first setup process. The settings will include:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 37 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Personal information (which are bound to a user profile in the Profile Nexus) Authentication data for the SiMa extensions Server connection configuration
4.2.4.5 Extension View This View will allow to access the Extensions configuration of the SiMa Device like to allow to do modifications to the Extensions for the SiMa device. It will include the following functionalities: Search for an Extension in the Service Marketplace Show details of an Extension Install new Extensions from the Service Market Place List currently installed Extensions Uninstall Extensions from the SiMa device List currently registered Extensions
4.2.4.6 Sensor View The Sensor View will help to interact with sensors in general. While it would not be able to display all data correctly, some common data, like for example degree in Celsius, will be shown correctly. The Sensor View will include the following functionalities: Connect to a sensor Disconnect from a sensor Display/Collect sensor data
4.2.4.7 Viki View With the help of the Viki View, the user is able to show, create and interact with Viki informations. It will include the following functionalities: Show, create and interact with Extended Visual Annotations (EVA), which are virtual notes attached to construction’s objects Show, create and interact with Extended Details Assets (EDA), which are instructions about how to install some components, through videos or texts
4.2.4.8 Project View The Project View will help to interact with informations concerning the site. It will allow to: Show the project schedule and all tasks in it Show a list of tasks, which have to be done by the authenticated user Show Task properties (like materials, users, current state, etc.) Create User/Work groups to assign different tasks to Create Tasks and schedule them
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 38 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.2.5 Interfaces
4.2.5.1 SiMa Services Third party apps will communicate with the SiMa Service via an Android service. Each SiMa app has to check at start up if the service is available. If this service is not available, it should be displayed, that the necessary ACCEPT app (the SiMa Service) has to be installed first. The service itself will be implemented as a bound service. A bound service allows components (such as activities) to bind to the service, send requests, receive responses and even perform interprocess communication (IPC). The service will manage its own lifecycle. It is supposed to always run in the background. Furthermore, to make the IPC possible, the Android Messenger class will be used. Each component, that expects an answer to its request, has to provide a Messenger-Instance in the ReplyTo - property. The binding to this service is shown in Listing 1. Every app developer has to connect to the service via the bindService() – method Android offers. Furthermore the name of the service has to be explicitly stated. The fully qualified name of the service is: eu.accept.sima.Service. Listing 1: Binding to the Service
bindService(new Intent("eu.accept.sima.Service"), mConnection, Context.BIND_AUTO_CREATE); Apps, which would like to talk to the service, must target that package. Furthermore, a Message features a so called “what”-parameter. This is an integer value allowing the SiMa Service to distinguish between different targets. Because of the “bundle” property, the parameters can be adopted for different needs. An example of registering an extension to the SiMa Service is described in 4.2.5.2.6.1. How it will look implemented is shown in the following listing: Listing 2: Send Message
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 39 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Most of the actions mentioned in the following chapters will use the Android app permission system. The information, which permission is needed can be found in the description and it will be added to the Android system like in the following example: Listing 3: XML permission
4.2.5.2 Services Every Service, which will communicate with different ACCEPT component will use the AMF. One exception will be the SAF, which will be integrated into the SiMa Service as a library. ID’s mentioned in the following chapters will be unique and are needed to identify one specific object.
4.2.5.2.1 Authentication
4.2.5.2.1.1 Authenticate in ACCEPT Authenticates the given user and stores an access token internally, which will be used in all other service calls. If the user is already authenticated, the authentication will logout the current user before the new authentication is used. If the user is not authenticated, the SiMa service will not respond on any other action. Action: login Parameters: userId: The ID of the user password: The password of the user Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.AUTHENTICATE ACCEPT Components used: None
4.2.5.2.1.2 Logout
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 40 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Deletes the user token and sets the SiMa Service in the unauthenticated mode, in which it just responds to the Authentication action. Action: logout Parameters: None Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.AUTHENTICATE ACCEPT Components used: None
4.2.5.2.2 Extension Handling
4.2.5.2.2.1 Install Extension Installs one extension of the SiMaApp from the Service Market Place. The SMP checks if the user is authorised to install the mentioned extension. Action: extensions.install Parameters: extensionId: The ID of the extension to install Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.EXTENSION_HANDLING ACCEPT Components used: SMP
4.2.5.2.2.2 Uninstall Extension Uninstalls an installed Extension from the SiMa device. Action: extensions.uninstall D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 41 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Parameters: extensionId: The ID of the extension to uninstall Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.EXTENSION_HANDLING ACCEPT Components used: None
4.2.5.2.2.3 List Available Extensions Lists all available extensions via the Service Market Place. Action: extensions.list Parameters: None Return Value: A List of Extension Id’s Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.EXTENSION_HANDLING ACCEPT Components used: SMP
4.2.5.2.2.4 Get Information About an Extension Gets the actual Information about an extension via the Service Market Place. It will include a description and so on. Action: extensions.details Parameters: extensionId: The ID of the extension to show the details from Return Value: An object, containing all informations of an extension Error Handling: D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 42 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
SAFException if any error arises. Permission needed: eu.accept.sima.EXTENSION_HANDLING ACCEPT Components used: SMP
4.2.5.2.2.5 List Installed Extensions Lists all extensions, which are installed on this device. Action: extensions.listInstalled Parameters: None Return Value: A list, containing all extensions Id’s of installed extensions Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.EXTENSION_HANDLING ACCEPT Components used: None
4.2.5.2.3 Sensor Handling
4.2.5.2.3.1 Receive Sensor Data Gets the actual sensor data of a sensor and stores it into the Profile Nexus. If the sensor is not connected directly to the SiMa device, the data is pulled from the Quality Profile of the Profile Nexus. Action: sensors.read Parameters: sensorId: The ID of the sensor to show the data from Return Value: An object, containing all informations of the received sensor data Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.SENSOR D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 43 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
ACCEPT Components used: SAF, PN (indirectly via SAF)
4.2.5.2.3.2 Attach to Sensor Attaches a component to a sensor. If any state changes happen, the component will be called automatically with the old and new sensor data. Action: sensors.attach Parameters: sensorId: The ID of the sensor to receive the data from receiver: The receiver, which should be notified Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.SENSOR ACCEPT Components used: SAF, PN/AMF event system (indirectly via SAF)
4.2.5.2.3.3 Detach from Sensor Detaches a component from a sensor, so it will not get notifications on state changes anymore. Action: sensors.detach Parameters: sensorId: The ID of the sensor to receive the data from receiver: The receiver, which gets notified Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.SENSOR ACCEPT Components used: SAF, PN/AMF event system (indirectly via SAF)
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 44 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.2.5.2.4 Media Data
4.2.5.2.4.1 Get Viki Element Receives the EVA or EDA data from the Visual Viki. Action: viki.load Parameters: vikiId: The ID of the viki element to receive the data from Return Value: The EVA or EDA object, which should be received. Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.VIKI_READ ACCEPT Components used: Viki
4.2.5.2.4.2 Store EVA/EDA Information Stores the EVA or EDA data to the Visual Viki. Action: viki.store Parameters: vikiId: The ID of the viki element to store the data to vikiObject: The EVA or EDA information, which should be stored Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.VIKI_MODIFY ACCEPT Components used: Viki
4.2.5.2.4.3 Delete EVA/EDA Deletes the EVA or EDA data from the Visual Viki. Action: viki.delete D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 45 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Parameters: vikiId: The ID of the viki element to store the data to Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.VIKI_MODIFY ACCEPT Components used: Viki
4.2.5.2.4.4 Get EVA/EDA Get the EVA or EDA information based on location data. Action: viki.location Parameters: locationData: The location data to receive the Viki information for. Return Value: A list of EVA/EDA informations with added positional data. Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.VIKI_READ ACCEPT Components used: Viki
4.2.5.2.5 Profile Nexus
4.2.5.2.5.1 Retrieve Profile Get the Profile from the Profile Nexus. Action: information.load Parameters: profileId: The ID of the profile, which should be loaded. Return Value: A profile containing the key and values of a profile from the Profile Nexus.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 46 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.INFORMATION_READ ACCEPT Components used: PN
4.2.5.2.5.2 Update Profile Updates the Profile from the Profile Nexus. Action: information.update Parameters: profile: The profile, which should be updated. Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.INFORMATION_MODIFY ACCEPT Components used: PN
4.2.5.2.5.3 Delete Profile Deletes the Profile from the Profile Nexus and every association to that profile from other profiles. Action: information.delete Parameters: profileId: The ID of the profile, which should be deleted. Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.INFORMATION_MODIFY ACCEPT Components used: D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 47 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
PN
4.2.5.2.5.4 Search for Profiles Searches for a Profile from the Profile Nexus. Action: information.search Parameters: pattern: The search pattern for the meant Profiles. It consists of attributes, relational operators, expected values, logical operators and grouping Return Value: A list of Profiles from the Profile Nexus Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.INFORMATION_READ ACCEPT Components used: PN
4.2.5.2.5.5 Attach to Profile Attaches to a profile. On any state changes of the Profile the attached extension will be notified. Action: information.attach Parameters: profileId: The ID of the Profile, which should be observed receiver: The receiver, which gets notified (optional) pattern: A pattern, which has to be fulfilled to get notified. It consists of attributes, relational operators, expected values, logical operators and grouping on different attributes of a profile Return Value: A list of Profiles from the Profile Nexus Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.INFORMATION_READ ACCEPT Components used: PN
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 48 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.2.5.2.5.6 Detach from Profile Detaches a receiver from a profile. Action: information.detach Parameters: profileId: The ID of the Profile, which should not be observed anymore receiver: The receiver, which got notified Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.INFORMATION_READ ACCEPT Components used: PN
4.2.5.2.6 App Handling
4.2.5.2.6.1 Register Extension Registers an Extension to the SiMa Service. Action: register Parameters: extensionId: The ID of the Extension, which should be registered. Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.ACCESS ACCEPT Components used: None
4.2.5.2.6.2 Deregister Extension Deregisters an Extension from the SiMa Service. The extension has to detach itself from all notifications made.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 49 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
(multiple notifications on the same data from different Extensions could detach a different extension as well) Action: deregister Parameters: extensionId: The ID of the Extension, which should be deregistered. (events?) Return Value: None Error Handling: SAFException if any error arises. Permission needed: eu.accept.sima.ACCESS ACCEPT Components used: None
4.2.6 Consumed Services Since the SiMaApp is one access point to the ACCEPT system, it consumes services from the Viki, Profile Nexus, SAF and SMP. The SiMa Service will route commands from a service to the correlating ACCEPT component through the AMF. It will utilise sensor data from the SAF; install/uninstall/list/show extensions and show detailed information of extensions with the support of the SMP; interact with EVA and EDA via the Viki; interact with the project, workflow and user profiles through the Profile Nexus and visualize sensor data stored in the Quality Profile of the Profile Nexus. For more details see Section 4.2.4.2.
4.2.7 Summary Several technologies have been taken into account to suit the needs of ACCEPT and the SiMaApp itself and were examined. The first step was to select a suitable device, which is future-proof, users are familiar with and give additional advantages. Googles Project Tango, which is running Android, was chosen. The second step was to select a suitable application framework, which is able to handle communications between apps and components while having a liberate license. This led to the Android Application Framework. Finally, the implementation details for the runtime environment were selected. The best fit for all requirements let to standalone Android apps interacting with the tools provided by the Android framework. Furthermore, the communication between third party apps has been specified, and also the necessary permissions.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 50 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.3 Construction Operator Application CoOpApp (Construction Operator Application) is an application running on smart glasses within the ACCEPT ecosystem. It provides some functionalities like creation of new Extended Visual Annotations (EVA), visualization of Execution Details Assets (EDA) and the capacity of taking pictures and recording video. All features are realised by using a smart glasses device.
4.3.1 Major Design Decision CoOpApp is a smart glasses application. It is able to display both EVA and EDA information that is Augmented Reality information. This information can contain different data formats, e.g. texts, images, videos or 3D models. The major design decision on this component is the choice of the most appropriated smart glasses. Regarding this, the software is easy to use by all kind of users and the wearing of the smart glasses is comfortable. Once the smart glasses device has been chosen, some limitations on the software that can be used with it, must be taken into account. These limitations are imposed by the device hardware. Commonly, the manufacturer specifies the development frameworks that are recommended to be used with their devices. CoOpApp should be easy to use for two reasons. Firstly, the environment in which it will be used (a construction) is a critical environment that needs total concentration in it to be safe, so if the application is complicate, the user should concentrate a lot in the application, not in the environment. Secondly, it is not a well-established device and probably most of the users will use them for the first time, so they are not used to know how they should apply the application to their work tasks.
4.3.2 Technology Comparison This subsection introduces different soft- and hardware technologies to develop the CoOpApp. In addition, it is also explained how to choose the best technology for developing this component easily and efficiently.
4.3.2.1 Smart glasses In the following list, some smart glasses, that are currently available in the market, are presented. There are different options available, like the Microsoft Hololens, Epson Moverio, Daqri Smart Helmet, Vuzix M100, etc. There are many other devices in this area, but some of them are only prototypes and they are currently not available. The Vuzix M100 Smart Glasses16 is an Android-based wearable computer, enhanced with a wearable monocular display. It has capabilities such as recording and wireless connectivity. Its pre-installed apps can be used to record and playback pictures and video, track timed events, calendar, link to a phone, etc. The M100 provides easy access to developer resources to enable the creation of custom apps
16 www.vuzix.com/consumer/products_m100 D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 51 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
to suit any need. The OS 2.0 version of M100 is built on Android Version 4.0.4 with many enhanced capabilities and a completely new user interface. The OS 2.0 version also supports Bluetooth 3.0 for the connection to the M100 enabling Bluetooth low energy. With OS 2.0 the M100 can run native M100 applications and most Android based legacy applications.
Figure 4: Vuzix M10017 The Epson Moverio BT 20018 is a smart glasses device, which consists of the glasses and a second device, the controller. There is no need for another smart phone or similar devices, because the controller has an integrated Android Operating System and uses a touchpad for navigation. It contains two screens (one per eye) and it can be used to display Augmented Reality data on both eyes, as can be seen in Figure 5. Epson Moverio works with Android platform, using Android 4.0.4 Ice Cream Sandwich version.
17 http://www.vuzix.com/consumer/products_m100/ 18http://www.epson.com/cgi-bin/Store/jsp/Landing/moverio-bt-200-smart- glasses.do?ref%20=van_moverio_2014 D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 52 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 5: Epson Moverio BT20019
DAQRI Smart Helmet20 (Figure 6) is a “heads up display” safety helmet with integrated Augmented Reality capabilities, which can enhance human abilities in many industries by seamlessly connecting the human being to the work environment and providing relevant information instantaneously. It has different sensors integrated. In addition, it uses augmented reality software and DAQRI’s Intellitrack system for precise display and tracking. DAQRI Smart Helmet OS is Android-based, so it is possible to develop an Android application for this smart helmet.
Figure 6: Daqri Smart Helmet Microsoft HoloLens21 (Figure 7) is a smart glasses unit that is a cordless, self- contained Windows 10 computer. It uses advanced sensors, a high-definition 3D optical head-mounted display and spatial sound to allow for augmented reality applications. These applications have a natural user interface where the user interacts with through gaze, voice, and hand gestures. To develop an application, Microsoft offers multiples technologies, whereby the most important programming languages are .NET languages or C++.
19 http://www.epson.com/cgi-bin/Store/jsp/Product.do?sku=V11H560020&UseCookie=yes 20 http://hardware.daqri.com/smarthelmet/ 21 www.microsoft.com/microsoft-hololens/en-us D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 53 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 7: Microsoft Hololens Considering the different types of devices, in order to choose the most appropriated one, the following specific parameter will be considered: Augmented Reality (AR): One of the most important features of this project is the AR. This characteristic is mandatory for the smart glasses to be chosen. In addition, the possibility to use an AR framework is better than to choose any smart glasses without this AR feature. Price: The top priority is to sell the resulting product. Therefore, a cheaper device is better while it has the adequate qualities for the project. Safety: The device must have a design that ensures the operator’s safety. It also has to be compatible with other security measures like helmets. The main features to fulfil in this field are three: The first one is not reducing the field of vision of the operators. The second one is not being harmful to their eyes. The last one to be kept in mind is that the glasses must not act as an element of distraction to the operator. Rugged: It is important that the selected device have been designed to operate in extremely harsh environments and conditions. There are three generally accepted levels of ruggedisation (the act of making a piece of equipment rugged - strengthening to resist wear or abuse): semi-rugged, fully-rugged and ultra- rugged22. These levels describe the product's ability to survive drops, vibration, dust, immersion and extreme temperatures. The device has to be able to survive in different construction environments.
22 http://whatis.techtarget.com/definition/rugged-IT D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 54 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 7: Smart Glasses comparison
Parameter Importance Vuzix Moverio Daqri Hololens Maturity & Stability & Quality +++ + +++ - -
Extensibility +/- ++ ++ ++ +
Open Source & Standards ++ +++ +++ ++ -
Familiarity / Support / +++ + ++ - + Community Performance / Scalability +++ - +++ ++ +++
State of the Art ++ ++ +++ - -
EU Project Origin - - - - - Licenses ++ +++ +++ -- -
Specific Parameters
AR +++ +++ +++ +++ +++
Safety + - ++ - +
Rugged ++ - ++ - -
Price +++ + ++ -- -
4.3.2.1.1 Technology Selection After the review of the previous subsection, the Epson Moverio BT-200 model has been chosen. The relation between the price and the quality of the device is the best of all the reviewed smart glasses. In addition, it is very easy to use. Another important detail is that the Moverio design enables the operator to wear his security helmet, and its stereo vision does not require the operator diverting his attention to a screen. The best option from a technological point of view is Microsoft Hololens, because they include several technological advances, like holograms, Augmented Reality and Virtual Reality, but they have an exorbitant price, they are not rugged, etc.
4.3.2.2 Frameworks AR frameworks allow abstracting from the most expensive process of developing applications and focus on the product features. This reduces development time. They provide built-in functionalities, like managing internet connections or displaying 3D models. Without these, the developer would need to have expertise knowledge about OpenGL commands. It is more difficult to learn this technology and to develop the code. Codename One23 is a set of tools for mobile application development that derive a great deal of its architecture from Java. It stands both as the name of the start-up that created the set of tools and as a prefix to the distinct tools that make up the
23 https://www.codenameone.com D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 55 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Codename One product. It is a free open-source solution that allows developers to TM rapidly build native applications to all mobile devices using Java . Optionally a GUI builder permits this, too. The framework brings full access to the underlying native platform while still providing remarkable portability. Codename One consists of a client library, IDE plugin, designer tool (GUI builder, theme designer, localization editor etc.), simulator environment, build servers & cloud provisioning services. Marmalade24 SDK is a cross-platform game and app development kit that enables developers to write code and deploy their apps to all major platforms, including iOS, Android, Windows Phone and desktop. Marmalade permits developers to code in C++ with full support for standard libraries and 3rd party extensions. It removes the need to use platform tools, languages, and APIs to replace them with a single API and tool-chain that is easy to use. Using a single project and a common code base developers are able to work on a Mac or a PC and deploy their results to all platforms, including deployment to iOS from a PC. Android SDK25 is a set of development tools used to create applications for Android platform. The Android SDK includes the following: Required libraries, debugger, an emulator, relevant documentation for the Android application program interfaces (APIs), sample source code, and tutorials for the Android OS. Every time, Google releases a new version of Android, a corresponding SDK is also released. The development platforms include operating systems like Windows (XP or later), Linux and Mac OS X (10.4.9 or later). Android NDK26 (Native Development Kit) is a toolset allowing developers to implement parts of their apps using native-code languages such as C and C++. Typically, good use cases for the NDK are CPU-intensive applications, such as game engines, signal processing, and physics simulation. The NDK is not appropriate for most novice Android programmers. Therefore, it has little value for many types of Android apps. Often, a usage is not worth the additional complexity it inevitably brings to the development process. However, it can be useful in cases in which you need to get extra performance of a device for applications with computational effort like games or physics simulations. Another option with this framework would be re-use your own or other developers' C or C++ libraries. Titanium/Appcelerator27 gives the ability to create iPhone apps without knowing Objective-C or Android apps without Java. Titanium applications are written using HTML, JavaScript and CSS, with development tools and support for PHP, Ruby and Python. Applications can use Appcelerator APIs to access native features, user interface constructs and optional modules like analytics. Titanium links JavaScript to native libraries, therefore compiles it to bytecode. The iOS or Android SDK compiler then builds the package for the target platform. The programming language is JavaScript and the code generated is transformed into native code at runtime. Basically, at runtime the application consists of three main components: Firstly, the source code in JavaScript, which is embedded in files Java or compiled Objective- C. Secondly, the Titanium API in native programming language, which is platform specific execution and through which it is possible to call native functions like GPS
24 https://www.madewithmarmalade.com/marmalade 25 http://developer.android.com/sdk/index.html 26 http://developer.android.com/ndk/guides/index.html 27 http://www.appcelerator.com/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 56 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
or the camera. Last but not least, the application inherits a JavaScript interpreter to execute code at runtime (V8-default-or Rhino for Android, and JavaScriptCore in for iOS). While compiling JavaScript code, Titanium does not cross to generate Objective-C or Java. Code written in JavaScript is executed at runtime. The communication between JavaScript and the native code is carried out by proxy objects. PhoneGap28 is a free and open-source framework for the creation of native-like mobile apps using standardized web APIs like HTML, CSS and JavaScript. In addition to standard web tools, PhoneGap enabled applications, which can utilize a JavaScript SDK to access native device capabilities. Many native development environments provide the mobile component "WebView" as part of the framework of user interface (UI). The solution takes advantage of it to create a JavaScript API within a “WebView” being able to communicate asynchronously with the native code. The implementation method of the "bridge" layer or gateway is different depending on the platform: E.g. in iOS, when calling a contact list, the native method invocation passes a queue of requests sent to the gateway. PhoneGap is not a platform by itself but a mechanism used to add functionality to web applications natively. The framework should be used in conjunction with other JavaScript frameworks such as jQuery Mobile and Sencha. Using the name Apache Cordova29, PhoneGap has donated to the Apache Software Foundation (ASF) in October 2011. Apache Cordova is a set of device APIs enabling a mobile app developer to access native device function, such as the camera or accelerometer from JavaScript. Combined with a UI framework such as jQuery Mobile, Dojo Mobile or Sencha Touch, a Smartphone app can be developed by just using HTML, CSS, and JavaScript. Xamarin30 tools allow Microsoft .NET developers familiar with C# and .NET libraries to write applications for iOS (MonoTouch) and Android (Mono for Android) platforms. Desktop platforms are also supported by the broader Mono project. Xamarin does not intend to support Blackberry, citing lack of demand: Both Blackberry and Windows Phone support were specifically requested by around 5% of developers using Mono. Applications built with MonoTouch are pre-compiled to native iOS executables. MonoDroid for Android uses Just in Time (JIT) compilation by deploying an embedded runtime within the application. MonoTouch and Mono for Android are available as a free, perpetual trial that does not permit app publishing. Professional version licensing starts at US $400 a year per product. Unity31 is a cross-platform game engine used to develop games. It is a 3D engine and a user-friendly development environment. Easy enough for the beginner and powerful enough for the expert, Unity should interest anybody who wants to easily create 3D games and applications for mobile, desktop, the web, and consoles. It provides rich out-of-the-box functionality to create games and other interactive 3D content. Developers can use Unity to assemble their art and assets into scenes and environments, add lighting, audio, special effects, physics and animation,
28 http://phonegap.com/ 29 http://cordova.apache.org/ 30 https://xamarin.com/ 31 https://unity3d.com/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 57 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
simultaneously play test and edit games. When ready, they can publish binaries to their chosen platforms. The following metrics are used to compare these frameworks: Productivity: Specifically, the productivity that one can achieve using this framework. Is it faster to develop using one of these frameworks? Learning curve: It is important to consider how easy a developer is able to learn using a framework. An easy understandable one will be preferable than other one that it is more difficult. AR plugin: If the framework includes an AR plugin, it is considered better than other that does not have, because one of the most important things in this component is tracking the Augmented Reality. 3D Model: The chosen framework should allow rendering 3D models.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 58 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 8: Frameworks Comparison
Paramete Importan Codena Marmale Andro Andro AppAcelera Phoneg Xamar Unit r ce me One de SDK id id tor ap in y SDK NDK Maturity & +++ - ++ +++ +++ ++ ++ +++ +++ Stability & Quality
Extensibili +++ ++ ++ +++ +++ ++ ++ +++ +++ ty Open + +++ - +++ +++ +++ +++ - - Source & Standards
Familiarity +++ - ++ ++ - ++ ++ ++ ++ / Support / Communit y Performa +++ ++ ++ +++ +++ + - ++ +++ nce / Scalability
State of +/- + ++ +++ +++ ++ ++ ++ +++ the Art
EU ------Project Origin Licenses ++ +++ ++ +++ +++ +++ +++ -- +
Specific Parameters Productivi ++ ++ ++ -- --- +++ +++ +++ +++ ty + Learning ++ - ++ ++ + +++ +++ ++ ++ curve
AR Plugin +++ - - - +++ - - ++ +++
3D +++ + +++ - - - - ++ +++ Models
4.3.2.2.1 Technology Selection Unity is a framework that can be learnt very easily and allows the developer team to be very productive, because it facilitates the developer’s work. It provides all the tools needed to work with 3D models, enabling and encouraging them to visualize the stage. Unity has plugins to integrate the major AR frameworks. In addition, this framework facilitates the development of specific applications for smart glasses using its module Digital Eyewear. All this reasons make the Unity framework the best choice.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 59 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.3.2.3 Augmented Reality Frameworks AR frameworks allow abstracting from the most tedious and repetitive process of developing AR applications. They focus on the product features reducing the development time. They also provide functionalities like tracking the objects and the image recognition. Vuforia Platform32 is an Augmented Reality SDK for mobile devices that enables the creation of Augmented Reality applications. It uses computer vision technology to recognise and track planar images and simple 3D objects, such as boxes, in real- time. This image registration capability enables developers to position and align virtual objects, such as 3D models and other media, in relation to real world images, when these are viewed through the camera of a mobile device. The virtual object then tracks the position and orientation of the image in real-time, so that the viewer’s perspective on the object corresponds with their perspective on the Image Target. This platform provides advanced computer vision functionality for recognising images and objects in the user’s field of view. Vuforia introduces support for mixed reality and all-new digital eyewear. Vuforia provides APIs in C++, Java, Objective-C and .NET platform through an extension named Unity game engine. In this way, the SDK supports both native development for iOS and Android. It is also enabling the development of AR applications in Unity, which are easily portable to both platforms. Wikitude33 is a mobile augmented reality technology provider. The SDK includes image recognition and tracking, 3D model rendering, video overlay and location based AR. The SDK is available for Android and iOS operating system and is optimised for several smart eyewear devices. For example, the Moverio BT-200 Wikitude just released version 5 of their SDK integrating plenty new features, as Image recognition and tracking, location-based services with geo-data, video augmentations and 3D models and rendering. ARToolkit34 is a software library for building Augmented Reality (AR) applications. These are applications that involve the overlay of virtual imagery on the real world. Some features are: robust tracking, including natural feature tracking, strong camera calibration support, simultaneous tracking and stereo camera support, multiple languages supported, optimized for mobile devices and full Unity3D, and OpenSceneGraph Support. ARToolKit is runnable on multiple platforms like on Windows, Mac OS X, Linux, iOS and Android operating systems. ARToolKit can be easily ported to other new and experimental platforms. ARToolKit supports both video and optical see-through augmented reality. The following metrics are used to compare these frameworks: Productivity: Specifically, the productivity that one can achieve using this framework. Is it faster to develop using one of these frameworks? Learning curve: It is important to consider how easy a developer is able to learn using a framework. An easy understandable one will be preferable than other one that it is more difficult. Tracking: Ability to track models position is better than its absence
32 https://www.qualcomm.com/products/vuforia 33 http://www.wikitude.com/ 34 http://artoolkit.org/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 60 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Frame Makers: It is very important to consider if the framework can recognise markers in order to render the adequate model. Smart glasses support: As this component is intended to be used for a smart glasses application, it must support this kind of device. Image recognition: It is desirable to have image recognition in the framework.
Table 9: Augmented Reality comparison
Parameter Importance Vuforia Platform Wikitude ARToolkit
Maturity & Stability & Quality +++ +++ +++ ++
Extensibility +++ ++ + ++
Open Source & Standards + - - ++
Familiarity / Support / +++ ++ +++ + Community Performance / Scalability +++ +++ +++ ++
State of the Art +/- ++ +++ ++
EU Project Origin - - - -
Licenses ++ + - +
Specific Parameters
Productivity ++ +++ +++ ++
Learning curve ++ ++ +++ +
Tracking +++ +++ +++ +++
Frame Markers +++ +++ ++ +++
Smart glasses support +++ +++ +++ +
Image Recognition + +++ ++ ++
4.3.2.3.1 Technology Selection By using the Vuforia framework, AR applications can be developed faster in addition to support of specialised components like virtual buttons, which provide a better user experience (UX). It allows recognition of both images and natural patterns. This is a great advantage because it lets developers use minimally invasive markers with the environment, in which the application should work. Another advantage of this framework is the slightly accentuated learning curve that enables the integration of less experienced
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 61 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
programmers into the team more quickly. One of the features being contributed to the choice of Vuforia was its full integration with Unity and with the Moverio smart glasses by their specific plugins.
4.3.3 Component Structure This subsection explains the different parts of CoOpApp component, and how is the CoOp application structured. This is a three-layer application as shown in Figure 8:
Figure 8: UML Component Diagram – CoOp Components
4.3.3.1 Service Access This layer contains the access module, called Access Controller to the CoOpApp. This is the only way to access the CoOpApp. The task of this module is to forward the request to the Service Logic layer and to send the response back to the user. If any other layer changes, this layer does not change and is independent to the rest of layers. The Access Controller obtains the user location in order to know where the user is located at real time. It also obtains the user’s role to authorise and authenticate the access to other services, D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 62 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
this can be send from the Access Manager subcomponent. To obtain this location, it can use external services, or GPS positioning if available, reading QR codes, or other methods like geo-fence. Perfect localization is assumed but is out of the scope of the project.
4.3.3.2 Service Logic This layer contains the logic of the CoOp application. It can find a subcomponent to access the Marketplace (CoOp Marketplace), other subcomponent to call the smart glasses functionalities (Smart glasses functionality), the subcomponent to manage the pattern recognition (Pattern recognition Data mining subcomponent), the Access Control List subcomponent, and the CoOp Manager subcomponent. The CoOpApp manager contains the CoOpApp´s intelligence, namely all information about how to connect with other modules and submodules of the ACCEPT’s System. This component calls methods to get EDA and EVA information, creating the user/role-location pair to return the adequate EDA or EVA structure. It is also responsible for managing notification events to inform a user about any task received by the smart glasses from other component of the ACCEPT System. It manages the messages from the smart glasses to SiMaApp and Dashboard applications. This subcomponent is connected to the rest of Service Layer subcomponents to obtain different information from them. In order to communicate with other components of the ACCEPT System, CoOpApp uses the AMF component. The Pattern Recognition Data Mining Controller is the component for performing pattern recognition, e.g. to recognize a window. This component depends on the hardware and frameworks that are being used. For pattern recognition, Epson Moverio BT-200 and the framework Vuforia have been chosen. It is possible to combine them with the Smart Glasses Controller submodule. The Smart Glasses Controller is the subcomponent that contains all the functionalities of the smart glasses through its API. This controller can take pictures, capture QR codes, record videos, etc. It can be combined with the CoOpApp Manager submodule and it depends on the chosen smart glasses model. Epson Moverio BT-200 includes applications to take pictures, read QR codes and record videos. Therefore, this component needs to use these apps. As in the SiMaApp, the CoOpApp Marketplace Extension (CoMP) subcomponent should access to SMP and it is responsible for accessing the SMP and installing and managing apps and services to extend the CoOpApp. The communication between this component and SMP is made via the SMP Repository subcomponent in the service data layer.
4.3.3.3 Service Data This layer is responsible to manage the data of EVA and EDA and to manage information regarding user’s security, like authorisation and authentication aspects. Also is responsible to connect with SMP subcomponent. The EVA & EDA Handler subcomponent is responsible of getting EVA information and modifying it when the user with the appropriate role changes the information inside of it. This subcomponent sends and gets the EVA from the Visual Wiki, sending the user’s location and the user’s role for this. It adds the intelligence to call services and to get/set EVA information from ACCEPT System. Users only could receive EDA information, not D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 63 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
modifying or inserting new EDA within the system. All these operations are done via the AMF controller module of the ACCEPT system. The SMP Repository component is the component which manages the communication between CoOp MarketPlace and Service Market Place. The functionalities of this subcomponent are: searching for services in the Service Market Place, showing details of a service, installing new services, listing currently installed services and uninstalling services. The Access Manager subcomponent provides an interface for the security functionalities like authorisation and authentication to manage each user of the CoOpApp.
4.3.4 Interfaces This component does not offer services for other components. It only consumes other component’s services.
4.3.5 Consumed Services CoOpApp uses services from Visual Wiki to obtain AR information and to create new AR information. These services are shown in the next table. Table 10: Consumed Services
Consumed service by the CoOpAp
Service Section Reference
Get an Execution Details Assets Section 4.5.5.1
Get an Execution Details Assets by UID Section 4.5.5.2
Get Extended Visual Annotations Section 4.5.5.7
Get Extended Visual Annotations by UID Section 4.5.5.8
Replace an Extended Visual Annotations with other (modify) Section 4.5.5.10
Create a new Extended Visual Annotations Section 4.5.5.11
Delete Extended Visual Annotations Section 4.5.5.12
Delete Extended Visual Annotations by UID Section 4.5.5.13
Request Translate Extended Visual Annotations Section 4.5.5.9
4.3.6 Summary This section presents the Construction Operator App component for the ACCEPT System and a set of different technologies to develop this application. First, it is necessary to agree on an appropriate smart glasses device. Two choices are available, Microsoft Hololens and Epson Moverio, but the last one has been selected, because Epson Moverio is D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 64 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
present in the market for some years and it has a good support. In addition, it is running Android. Secondly, several frameworks to develop applications for wearables have been presented. Here, the framework Unity was chosen, which provides a plugin to develop Moverio applications. Related to this framework, it presents some AR frameworks, to facilitate working with this technology. Finally, the Vuforia framework was chosen to develop AR applications. Unity has a plugin for this framework. All these choices present the definitive component structure of the application. In addition, the communication tools between other components of the ACCEPT System were also presented in the section. 4.4 Dashboard
4.4.1 Overview The Dashboard is a client application, offering high-level views on the Quality metrics of the construction project. It extracts them from the large quantity of data available in the system. The goal is to provide synthetized views of the data, in order to enable the user to identify the elements of the construction project that needs its attention.
4.4.2 Major Design Decision The choice of a web application (HTML5) has been made over a desktop application, so that the Dashboard can run both on a stationary and on a mobile device. The goal is to enable the site manager to consult the Dashboard by using the same hardware device he is using for the SiMaApp. The Dashboard web app must adapt its layout according to the available screen surface (Responsive design). Like most modern web applications, the Dashboard will provide a user-experience that goes beyond the traditional HTTP paradigm (on each click, the browser sends a request and then waits for the response), providing a richer user experience. These are known as “Rich Web Applications”. The whole technological stack will be open-source (and, when possible, free for commercial applications). The Dashboard will be developed as a “long-term solution”. When choosing an IT technology, some importance should be put on how long the solution will be maintained and extended in the future. It requires a large community around this technology with a lot of documentation, tutorial and examples, for answering questions occurring when developing with it. The client application needs to display different charts and statistics. In addition, the capability of displaying and navigating 3D information can also be important to display building related data, so the selected technological stack should support these features.
4.4.3 Technology Comparison Different frameworks are available to develop web-applications. They can be grouped in three major categories:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 65 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Server-side only: All the code runs on the server, it generates HTML pages, and each click on the user-side makes a request to the server to generate another HTML page. Client-side mostly: The user interface is built on top of JavaScript (which is part of the html 5 standard and, as such, supported in most modern browsers), to provide an extensive user-experience. Hybrid: There are technologies, like GWT (Google Web Toolkit), that run from a single Java project and generate a server-side code and a client-side code compiled in JavaScript. The “server-side only” approach has been discarded because this solution offers a very limited user experience. Despite the interest of the hybrid approach, it is currently limited to the sole graphical elements available in GWT. On the other hand, there is a huge list of libraries available in JavaScript, making the client-side approach an excellent choice for our given goals. There are different technologies for the client-side development: Pure JavaScript: As JavaScript is the base language for all rich-client web application, as it is a natural candidate for this. There are a lot of libraries developed for it. However, the language has evolved from small scripting needs to the current needs of web applications. Therefore, it is strangely structured and lacks modern capabilities for developing large-scale, well-documented and well tested applications. Dart: It is an initiative from Google, following the idea “What would a web language look like if it was developed from the scratch today?” It is a state-of-the-art language, designed for large and extensible applications. It is compiled in JavaScript, so that it runs on any browser available. It provides some support for external libraries developed in pure JavaScript. Several of the most famous JavaScript libraries have already been ported into Dart libraries. TypeScript: It is a recent initiative from Microsoft. It is a ‘syntactical’ improvement of JavaScript. It can be considered as an intermediate effort, between JavaScript and Dart. As it is closer to JavaScript it is easier to learn for web-developers having a previous experience in JavaScript. TypeScript has gained a lot of momentum over the last few months. It is able to run all available JavaScript libraries. There are other alternatives of less significant impact, like Babel or CoffeeScript. They compile the latest version of JavaScript into an older JavaScript format, in order to remove all versioning issues on the different browsers. Any of these solutions will require additional libraries to fulfil all the requirements of the Dashboard. Here is a selection of the most known such libraries: Responsive design: Bootstrap is a JavaScript library developed by Twitter, to reach a responsive design and interface, i.e., have a web-site that can adjust its layout based on the available screen-surface. Bootstrap has a port to Dart. For example, here is the same page from the LUCID-IDS web page, at different screen sizes:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 66 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 9: Examples of Responsive Design of a Web Page Rich UI: There are many libraries that provide an extended list of useful user interface elements. The most widely used is JQuery. JQuery has a port to Dart, called DQuery. There is also “React” which is gaining momentum (https://facebook.github.io/react/). Chart UI: There are different libraries to render charts in web-pages. To name only a few, there are Chart.js, D3.js or Google charts. Chart.js has a port to Dart, called ChartDart. 3D UI: Some JavaScript libraries offer scenographic 3D capabilities. ThreeJS is one of them; it provides a good API and decent performances, as well as Dart port called ThreeDart. Application architecture: There are multiple libraries helping on the structural side of web-applications. Two of them are ‘AngularJS’ and ‘Backbone’. They also provide helpers for Web-services interactions. Angular is an interesting technology from Google, and it is oriented toward automated testing of web-applications. AngularJS has a port to Dart, called AngularDart. PureMVC: It is a library implementing the MVC paradigm (Model-View-Controller), allowing a strong decoupling between the data management, the user interface component and the logic between the two. Both, JavaScript and Dart have a PureMVC port, called “PureMVC Dart”. The following table compares these technologies. The generic parameters have already been described in the previous sections. The specific parameters are: Code quality: It is well known that JavaScript, which is used in most dynamic web- applications, offers poor design constructs for building large and extensible applications. It is most important that a state-of-the-art programming language is used in the project, offering the required constructs for a well-structured and easy to maintain code. Unit testing: Web development technologies usually lack of testing features. However, at the same time, these testing capabilities are central to modern software development technologies. UI tools: Because the challenges of the Dashboard development largely lies in its User Interface, it is important to indicate whether the evaluated technology already comes with a rich set of integrated UI components or not.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 67 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 10: Dashboard Technology Comparison
Parameter Importance Dart TypeScript Babel CoffeeScript
Generic Parameters
Maturity & Stability ++ ++ ++ + +
Extensibility +++ +++ ++ + ++
Open source / standard ++ +++ ++ + -
State of the art +++ +++ ++ + +
Performance / scalability + ++ ++ ++ ++
Familiarity / Community +++ ++ + + +
License + BSD Apache 2.0 MIT License MIT License
Specific Parameters
Code Quality +++ +++ +++ ++ +
Unit testing ++ +++ ++ ++ +
UI tools ++ +++ + + +
4.4.3.1 Technology Selection Dart framework has been chosen for building the Dashboard, based on the table above comparing the different technologies. Because Dart is built on top of JavaScript and JavaScript is far more mature (web standard), there is still the possibility to resort to JavaScript if Dart will demonstrate lacking functionalities in some areas. Below is the stack of technologies this client will be built upon.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 68 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Dashboard App
App architecture Core UI Advanced UI Angular.Dart Bootjack ChartDart Dart PureMVC Dart D.Query ThreeDart
Angular.JS Bootstrap ChartJS JS PureMVC JS J.Query ThreeJS
HTML 5 Figure 11: Stack of technologies The technologies illustrated in Figure 11: Stack of technologies are described in the previous section. The Dashboard will be fully developed at the Dart level. However, there is still the capability to use the JavaScript layer if some library ports had issues of if there are some problems found in the still young Dart language. JavaScript is only here as a backup solution.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 69 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.4.4 Component Structure
Figure 12: UML Component Diagram - Dashboard The dashboard application will be built using the Pure MVC pattern (MVC stands for Model-View-Controller). As such, the application is structured as a 3-tier architecture. These 3 layers are illustrated in Figure 12: UML Component Diagram - Dashboard and described in the next section.
4.4.4.1 Data Tier
4.4.4.1.1 ACCEPT Access This component provides an interface to access the different data sources available in the ACCEPT system. It will hide the communication mechanism (WebServices) and will be able to communicate asynchronously with other components of the application thanks to the PureMVC notification mechanism.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 70 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.4.4.1.2 Local Model Most of the information will be stored in the distributed ACCEPT system. Still, a few data will have to be stored locally, using cookies. For example if a user wishes the Dashboard application to remember its login and/or password, it becomes part of the local data store. The user preferences may go to the local model or may be stored in the user profile. Either way, this component provides a unified way to access these local data.
4.4.4.1.3 Authentication As for every client application, the Dashboard requires a user authentication for each new session. This component encapsulates the accesses to the Authentication services provided by the User Profile Nexus.
4.4.4.1.4 Authorisation The same goes for the authorisation. It is managed within the User Profile Nexus. This component encapsulates these services.
4.4.4.1.5 Data Proxies The Data layer of the architecture can be integrated into the PureMVC framework with a layer called ‘Data Proxies’. The proxies are responsible for linking the data access with the notification mechanism at the heart of PureMVC. For example, a component can make a request through a notification. This notification is captured by the relevant proxy, which decodes and transforms it into the proper request to the data access. Then the proxy communicates the result through another ‘answer notification’.
4.4.4.2 Logic Tier
4.4.4.2.1 PureMVC Notification Bus All interactions between the different components are managed in the PureMVC Notification Bus. It defines the notification structure and dispatches these notifications to the relevant registered components.
4.4.4.2.2 Widget Deployment Manager This component encapsulates the logic for the widget-base extensibility of the Dashboard. The Dashboard will allow new widgets (extensions) to be added. This component provides the framework to enable such extensibility.
4.4.4.2.3 Commands Controller The PureMVC framework proposes to encapsulate the logic/controller operations in Commands. Commands are able to communicate with other components through notifications. The basic commands for the Dashboard will be the application start-up, the login activity, the management of the widgets, or any useful generic commands that can serve as an API for developing the widgets.
4.4.4.3 UI Tier The UI tier is only responsible for implementing all the user interface elements, without any knowledge of the business logic of the Dashboard.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 71 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.4.4.3.1 Widget Host The UI component is responsible for managing the multiple widgets in the interface. It offers the capability to add, remove or customize widgets. It also defines the presentation layout for organizing the widgets.
4.4.4.3.2 Widget Mediators The Widget Mediators are the connection between the PureMVC framework and the pure UI components. Mediators are able to send and react to PureMVC notifications.
4.4.4.3.3 Many Widgets UI This is the place where all developed widgets will be located. Each widget will fulfil a very specific requirement, and each requirement will be implemented as a separate widget. This strategy insures the extensibility of the whole Dashboard application.
4.4.5 Interfaces As this is a client application, it does not provide any external services, it just consumes services from server-side modules.
4.4.6 Consumed Services In addition to the common services consumed by all the clients (Authentication / Authorisation), and for extensible clients (install/uninstall/list/show extensions and show detailed information of extensions with the support of the SMP), the Dashboard uses the services below. The list of services is limited as most of the work is done by the quality profile, which is responsible for aggregating the quality data. Table 11: Services Consumed by Dashboard
Consumed service by the Dashboard
Service Section Reference
Get Execution Details Assets 4.5.4.3
Get Execution Details Assets by UID 4.5.4.3
Replace an Execution Details Assets with other (modify) 4.5.4.4
Create a new Execution Details Assets 4.5.4.5
Delete an Execution Details Assets 4.5.4.6
Get Metric in Quality Profile 4.8.3.2.5
4.4.7 Summary The Dashboard is a web application. It will use a modern stack of technologies to enable a rich and responsive interface, as well as a structured and tested program code. It will use the MVC pattern to decouple different components and easily compare different UI
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 72 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
prototypes. It is also an extensible application, thanks to the notion of widgets, which are small applications dedicated to a targeted set of functionalities.
4.5 Visual Wiki
4.5.1 Overview The Visual Wiki (Viki) is a server application that provides different services to manage Augmented Reality (AR) information of the ACCEPT System, e.g., the Execution Details Assets (EDA) and the Extended Visual Annotations (EVA). These services are the basis to allow the linking of information to real world objects. Viki is responsible for managing the requests from the SiMaApp, CoOpApp and Dashboard components. By using the Autonomous Messaging Framework (AMF), it stores and retrieves the information into/from the Knowledge Information Storage (KIS) component. Finally, the Viki is responsible to perform object detection from construction to offer adequate AR information.
4.5.2 Major Design Decision As it is responsible of managing Augmented Reality, Visual Wiki communicates with each other component that needs this AR information by using web services. It also checks if user the permissions are of the user is correct to request or store AR augmented reality information.
4.5.3 Technology Comparison
4.5.3.1 Communication Frameworks These frameworks provide functionalities for communication and storage. Viki offers RESTful web services and uses JSON data format to exchange information. REST is a standard based on web standards and the HTTP protocol. In REST based architectures, everything is a resource. Resources are accessed by using a common interface based on the HTTP standard methods. In this kind of architectures, typically a REST server is present, which provides access to the resources and a REST client, which accesses and modifies the resources. Every resource should support the HTTP common operations. Resources are identified by global IDs (typically URIs). REST allows resources to have different representations, e.g., text, XML, JSON etc. The REST client is able to ask for a specific representation via the HTTP protocol (content negotiation). RESTful web services are based on HTTP methods and the concept of REST. A RESTful web service typically defines the base URI for the services, the supported MIME-types (XML, text, JSON, user-defined, etc.) and the set of operations (POST, GET, PUT, DELETE), which are supported. JSON (JavaScript Object Notation) is a lightweight data-interchange format and it is easy to read and write for humans, as well as for machines to parse and generate. JSON is a text format that is language independent. It is based on a subset of the JavaScript
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 73 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
programming language. These properties make JSON an ideal data-interchange language. In the following, several frameworks are present: Apache Thirft35 is a software framework for developing scalable cross-language services. It combines a software stack with a code generation engine to build services that work efficiently and seamlessly between C++, Java, Python, PHP, andother languages. Thirft can be used to define statically typed, enforceable schemas. It provides an interface definition language to describe the schema in terms of generic data types. This description can later be used to automatically generate the current implementation in multiple programming languages. In this language the developer is able to define the functions and their corresponding parameters. Afterwards, the Thrift compiler is used to generate corresponding code for any language. This is used by Facebook, for example. Protocol Buffers36 are Google's language- and platform-neutral extensible mechanism for serializing structured data. This platform allows the definition of the way to structure data. After that, it generates source code to and from a variety of data streams using a variety of languages. Protocol Buffers is very similar to the Apache Thrift protocol, by except that the public Protocol Buffers implementation does not include concrete RPC protocol stacks to be use for defined services. A software developer defines data structures (called messages) and services in a proto definition file (.proto) and compiles it with protoc. This compilation generates code that can be invoked by a sender or recipient of these data structures. Avro37 is a data serialization framework developed within the Apache's Hadoop38 project. It uses JSON for defining data types and protocols, and serializes data in a compact binary format. It is primary used in Apache Hadoop, where it provides both a serialization format for persistent data and a wire format. The wire format is for communication between Hadoop nodes and from client programs to the Hadoop services. It is similar to Thrift, but does not require running a code-generation process when a schema changes (unless desired for statically-typed languages). RESTEasy39 is a JBoss project providing various frameworks to build RESTful web services and RESTful Java applications. Its implementation follows the JASX-RS specification. RESTEasy can run in any servlet container. Some features of RESTEasy are the fully certified JAX-RS implementation, the portability to any app- server/Tomcat that runs on JDK 6 or higher and the embeddable server implementation for JUnit testing. Furthermore, the client framework leverages JAX- RS annotations so it is possible to write HTTP clients easily. The client’s "browser" cache supports HTTP 1.1 caching semantics including cache revalidation. This framework works with a rich set of providers for XML, JSON, YAML, Fastinfoset, Multipart, XOP, Atom and more.
35 http://thrift.apache.org 36 https://developers.google.com/protocol-buffers/ 37 https://avro.apache.org/ 38 https://hadoop.apache.org/ 39 http://resteasy.jboss.org/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 74 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Jersey40 is the reference implementation for the JSR 311 specification. It provides its own API, which extends the JAX-RS toolkit with additional features and utilities to further simplify RESTful services and client developments. The Jersey implementation provides a library to implement RESTful web services in a Java servlet container. On the server side, Jersey provides a servlet implementation which scans predefined classes to identify RESTful resources. The Jersey implementation also provides a client library to communicate with a RESTful web service. Therefore, a REST web application consists of data classes (resources) and services. These two types are typically maintained in different packages as the Jersey servlet will be instructed via the “web.xml” to scan certain packages for data classes. JAX-RS supports the creation of XML and JSON via the Java architecture for XML Binding (JAXB). Restlet41 is a lightweight, comprehensive, open-source REST framework for the Java platform. Restlet is suitable for both server and client web applications. It supports major Internet transport, data format, and service description standards like HTTP(S), SMTP, XML, JSON, Atom, and WADL. A GWT port of the client-side library is also available. Restlet provides a reusable and extensible set of classes and interfaces to construct own API-driven applications. Each core REST concept possesses an equivalent Java artefact in the Restlet framework, including resource, representation, connector and component. HTTP headers are also mapped into classes like MediaType. The solution uses the same API for both client-side and server-side applications. Restlet Framework implements "URIs as UI", based on the URI Templates standard, resulting in a very flexible yet simple routing with automatic extraction of URI variables into request attributes. The built-in tunnelling service lets browsers issue any HTTP method (PUT, DELETE, MOVE, etc.) through a simple HTTP POST. This service is transparent for Restlet applications. Apache CXF42 implements the JAX-WS APIs, which makes building web services easy. JAX-WS encompasses many different areas. First: Generating WSDL from Java classes and vice versa. Another area is the Provider API, which allows creating simple messaging receiving server endpoints. Apache CXF is an improvement over AXIS2, which is now gradually being replaced by Apache CXF. It is intuitive and easy to use (less coding required as compared to AXIS2). In addition, it comes with a clean separation of front-ends, like JAX-WS from the core code. CXF is fully compliant with JAX-WS, JAX-RS and others. There is a support for a wide variety of front-end models and both JAX-WS and JAX-RS (for RESTful Services). Last but not least, there is compatibility with Spring Framework. The specific parameters for the communication framework are the following: Neutrality: It is important to separate the language and the message to be transmitted in the system. Independence: This means that multiple programming languages are supported. As a result, the framework is independent of it. Large Data Handling: It tells that the system must be able to manage huge amounts of data, which is important to be considered.
40 https://jersey.java.net/ 41 http://restlet.com/ 42 http://cxf.apache.org/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 75 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Simplicity: It is important that it is easy to use. Serialization: If the framework can wrap and unwrap the data model automatically, a developer is more productive with it. Table 12: Communication Frameworks Comparison
Parameter Importance Apache Protocol Avro RestEasy Jersey Restlet CXF Thrift Buffers
Maturity & ++ ++ +++ + +++ +++ +++ +++ Stability & Quality Extensibility +++ + + + +++ +++ +++ ++
Open Source & +++ +++ +++ +++ +++ +++ +++ +++ Standards
Familiarity / +++ ++ ++ - +++ ++ ++ ++ Support / Community Performance +++ +++ +++ +++ ++ ++ ++ ++
Scalability +++ + + + +++ +++ +++ +++
State of the Art +/- ++ ++ - ++ ++ ++ ++
EU Project ------Origin
Licenses - +++ +++ +++ +++ +++ +++ +++
Specific Parameters Neutrality ++ ++ + + +++ +++ +++ +++
Independence +++ ++ + ++ +++ +++ +++ +++
Large Data +++ ++ + + + + + + Handling
Simplicity ++ + ++ ++ +++ +++ +++ ++
Serialization ++ +++ +++ +++ - - - +
4.5.3.1.1 Technology Selection Taking the comparison into account, there are two possible frameworks to be use: RestEasy and Jersey. Both are very similar and they adapt to the Viki functionality. RestEasy is probably more convenient due to the community support and because RestEasy includes some security aspects that Jersey does not support, like OAuth 2.0 principles. In general, RestEasy includes the majority of functionalities of Jersey and it
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 76 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
improves others. Therefore, it is more complete and useful than Jersey. For this, RestEasy is selected.
4.5.3.2 Translation Frameworks One of the features of the Visual Wiki is the ability to translate Virtual Notes from different languages. For this, it presents different technologies: Google Translator Toolkit43 is a tool that automatically translates text from one language to another (e.g. French to English). The Google Translate API can be used to programmatically translate text in the web pages or apps. The Google API client libraries, which are available in a number of popular programming languages, make it easy to use the Google Translate API. The purpose of it is to help making content accessible to users in their own language. Accordingly, there are certain attribution and linking requirements. There are some issues about the use of Google Translate. Firstly, applications using the Google Translate API must state in the application description and help documentation that Google Translate is used to power translation within the application and provide links to the Google Translate site. Secondly, if unaltered translation results are displayed on web pages that can be indexed by search engines, it is required to designate the translated text as machine translated content using the HTML markup reference. itranslate4.eu44 is an open translation site for all online translators. It is initiated by a consortium of European companies under the framework of the European project ICT PSP CIP-ICT-PSP-2009-3 Pilot Type B. It has functionalities like: machine translation of short texts and web pages; spellchecking, virtual keyboard, it allows automatic language detection, domain selection, translated search and an interface for technical feedback and user contribution. Finally, it has a quality control by regular evaluation to foster competition between the different providers and it has a gateway to professional human translators. It includes a common API for translation services. Talkamatic45 is a tool combining natural dialogue with easy-to-use dialogue interfaces, low user distraction and high usage efficiency. Talkamatic is based on research from the department of Linguistics, Philosophy and Theory of Science, University of Gothenburg. The business idea is to build and sell multi-modal dialogue systems based on research on human-human dialogues. It allows end- users to talk freely to an application. The Talkamatic feedback model goes far beyond the standard concepts of “explicit and implicit verification”, providing users with the right feedback at the right time. It offers high-level dialogue scripting, extremely rapid development and 3rd party application development of voice interaction on top of the existing application UI. As specific parameters for this case, the following are considered: Simplicity: It describes the easiness in using the translator Number of words: Specifically, how many words can be translated with the tool?
43 https://translate.google.com/toolkit 44 http://itranslate4.eu/ 45 http://talkamatic.se/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 77 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 13: Translation Framework Comparison
Parameter Importance Google Translator iTranslate4.eu Talkamatic Toolkit
Maturity & Stability & Quality +++ ++ ++ ++
Extensibility +/- +++ +++ +
Open Source & Standards + - - -
Familiarity / Support / Community +++ ++ ++ +
Performance / Scalability +/- ++ ++ ++
State of the Art ++ +++ + ++
EU Project Origin - - - -
Licenses ++ + + --
Specific Parameters
Simplicity +++ +++ +++ ++
Number of words +++ - + -
4.5.3.2.1 Technology Selection One option here is Google Translator, because it has a much wider community than other tools and it is continuously improving its translations thanks to the community. The other option to use is iTranslate4.eu. This European project can be a good option to reuse in other European project. Both work in a similar way, through REST web services, but the Google Translator API is not free of charge46 and iTranslate47 is free for the first 10.000 characters. Therefore, the iTranslate4.eu tool has been chosen.
4.5.4 Component Structure This section describes the way the Visual Wiki is structured and furthermore the different components of it. This is a three-layer application as we can see in Figure 13.
46 https://cloud.google.com/translate/v2/pricing 47 http://itranslate4.eu/es/webshop/index D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 78 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 13: UML Component Diagram – Viki Components
4.5.4.1 Service Access The Viki API is the access subcomponent to the Visual Wiki component. This is the only way to access the Viki. As other subcomponents of the ACCEPT System in the Service Access layer, the task of this module is to forwards the request to the Service Logic layer and sends the response back to the Dashboard, the CoOpApp or the SiMaApp.
4.5.4.2 Service Logic Viki Controller is the component that manages the request from the Service Access Layer to send the Viki data. It calls to the Access Manager in the Service Data to use security aspect of the application. In addition, it uses the EVA&EDA Controller to store and retrieve Augmented Reality information from other ACCEPT components. Moreover, it calls the Image Recognition subcomponent to obtain an AR object.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 79 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
EVA&EDA Controller is the controller to get and send EVA and EDA information. It communicates with the AMF controller to store and retrieve EVA/EDA information. This submodule parses the information retrieved from AMF services to send them to the User Manager. EVA&EDA Controller also allows the translation of an EVA from one language to another. The Image Recognition subcomponent is responsible to manage the information obtained from performing an image recognition task in order to offer the adequate AR object or list of objects. This subcomponent receives an image of an object from the SiMaApp or CoOpApp and should offer information through EDA objects, based on the image.
4.5.4.3 Service Data Data Handler Controller is responsible for managing the communication with the AMF Controller component and the KIS module. It contains the methods to call AMF services to interact with other ACCEPT components like KIS or Profile Nexus and the logic to store or retrieve information from the ACCEPT System. The Access Manager is responsible for integrating the Security of the component (Authentication and Authorisation) and sending this information to the Viki Controller.
4.5.5 Interfaces This section shows the interfaces provided by Visual Wiki to manage EVA and EDA Information. To follow the REST standards the base URL used in the request URL is the following: http://accept-project.com/viki/.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 80 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.5.5.1 Get Execution Details Assets Table 14: GetEDA interface Information of an Service by Version Description Get Execution Details Assets Request Request URL GET http://accept-project.com/viki/getEDA/ Resource Name Description Parameters userId Required User ID integer Example: 21842
Location Location of the user Optional location Example: 2 Floor, 1 section (or GPS coordinates)
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: getEDA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png List of EDA objects in a certain proximity of the users EDA object or null location or null if there are not EDA values in this Required EDA location Example: EDA1, EDA5, … Whether the service has already been published or published not Required boolean Example: true
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 81 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.2 Get Execution Details Assets by UID Table 15: GetEDAByUID interface Information of an Service by Version Description Get Execution Details Assets by UID Request Request URL GET http://accept-project.com/viki/getEDAByUID/ Resource Name Description Parameters userId User ID Required integer Example: 21842
objectUID object UID Required int Example: 12345 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842
name The name of the service Required string Example: getEDAByUID
version The version of the service Required string Example: 1.0
date The date of publication Required string Example: 23/05/2015
iconUrl The url of the icon of the service Required string Example: /assets/icon.png
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 82 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
list of EDA objects nearest to the user EDA object or null location or null if there are not EDA values Required List of EDA in this location Example: EDA1, EDA5,…
Whether the service has already been published published or not Required boolean Example: true
author The name of the author Required string Example: John
supportContact The support contact of the service Required string Example: [email protected]
4.5.5.3 Modify Execution Details Assets Table 16: putEDA interface Information of an Service by Version Description Replace an Execution Details Assets with other (modify) Request Request URL PUT http://accept-project.com/viki/putEDA/ Resource Name Description Parameters userId User ID Required integer Example: 21842
EDA_ID EDA identification Required int Example: 12345
newEDA The new EDA to insert Required EDA object Example: EDA4
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 83 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: putEDA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.4 Create a new Execution Details Assets Table 17: PostEDA interface Information of an Service by Version Description Create a new Execution Details Assets Request Request URL POST http://accept-project.com/viki/postEDA/ Resource Name Description Parameters userId User ID Required integer Example: 21842
EDA_ID EDA identification Required int Example: 12345
newEDA The new EDA to insert Required EDA object Example: EDA10
Response
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 84 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: postEDA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.5 Delete an Execution Details Assets Table 18: DeleteEDA interface Information of an Service by Version Description Delete an existing Execution Details Assets Request Request URL DELETE http://accept-project.com/viki/deleteEDA Resource Name Description Parameters userId User ID Required integer Example: 21842
EDA_ID EDA identification Required int Example: 12345
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 85 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: deleteEDA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.6 Delete Execution Details Assets by UID Table 19: DeleteEDAByUID interface Information of an Service by Version Description Delete an Execution Details Assets by UID Request Request URL DELETE http://accept-project.com/viki/deleteEDAByUID Resource Name Description Parameters userId User ID Required integer Example: 21842
EDA_UID EDA UID Required int Example: 12345
Response HTTP Status Value Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 86 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Code 200 OK 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: deleteEDAByUID version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.7 Get Extended Visual Annotation Table 20: GetEVA interface Information of an Service by Version Description Get Extended Visual Annotation Request Request URL GET http://accept-project.com/viki/getEVA/ Resource Name Description Parameters userId User ID Required integer Example: 21842
Location Location of the user Optional location Example: 2 Floor, 1 section (or GPS coordinates)
Response HTTP Status Value Description Code 200 OK
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 87 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: getEVA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png list of EVA objects nearest to the user location or null EVA object or null if there are not EVA values in this location Required EVA Example: EVA1, EVA5,… Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.8 Get Extended Visual Annotations by UID Table 21: GetEVAByUID interface Information of an Service by Version Description Get Extended Visual Annotations by UID Request Request URL GET http://accept-project.com/viki/getEVAByUID Resource Name Description Parameters
userId User ID Required integer Example: 21842
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 88 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
UID EVA UID Required int Example: 12345
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842
name The name of the service Required string Example: getEVAByUID
version The version of the service Required string Example: 1.0
date The date of publication Required string Example: 23/05/2015
iconUrl The url of the icon of the service Required string Example: /assets/icon.png
List of EVA objects nearest to the user EVA object or null location or null if there are not EVA values in Required List of EVA this location Example: EVA1, EVA5,…
Whether the service has already been published published or not Required boolean Example: true
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 89 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
author The name of the author Required string Example: John
supportContact The support contact of the service Required string Example: [email protected]
4.5.5.9 Get Translated Extended Visual Annotations Table 22: GetTranslateEVA interface Information of an Service by Version Description Get the translated version of a UID specified Extended Visual Annotations Request Request URL GET http://accept-project.com/viki/translateEVA/ Resource Name Description Parameters
userId User ID Required integer Example: 21842
UID EVA UID Required int Example: 12345
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842
name The name of the service Required string Example: translateEVA
version The version of the service Required string Example: 1.0
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 90 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
date The date of publication Required string Example: 23/05/2015
iconUrl The url of the icon of the service Required string Example: /assets/icon.png
List of EVA objects nearest to the user location EVA object or null or null if there are not EVA values in this Required List of EVA location in other language Example: EVA_es1, EVA_es5,…
Whether the service has already been published published or not Required boolean Example: true
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.10 Modify an Extended Visual Annotations Table 23: PutEVA interface Information of an Service by Version Description Replace an Extended Visual Annotations with other (modify) Request Request URL PUT http://accept-project.com/viki/putEVA Resource Name Description Parameters userId User ID Required integer Example: 21842
EVA_ID Identification of the EVA Required int Example: 12345
newEVA The new EVA to insert Required EVA object Example: EVA4
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 91 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: putEVA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: support@ john.com
4.5.5.11 Create an Extended Visual Annotation Table 24: PostEVA interface Information of an Service by Version Description Create an Extended Visual Annotation Request Request URL POST http://accept-project.com/viki/postEVA Resource Name Description Parameters userId User ID Required integer Example: 21842
EVA_ID EVA identification Required int Example: 12345
newEVA New EVA to insert Required EDA object Example: EVA11
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 92 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: postEVA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.12 Delete an Extended Visual Annotation Table 25: DeleteEVA interface Information of an Service by Version Description Delete an Extended Visual Annotation Request Request URL DELETE http://accept-project.com/viki/deleteEVA Resource Name Description Parameters userId User ID Required integer Example: 21842
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 93 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
EVA_ID EVA identification Required int Example: 22345
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: deleteEVA version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.5.13 Delete Extended Visual Annotations by UID Table 26: DeleteEVAByUID interface Information of an Service by Version Description Delete an Extended Visual Annotation by UID Request Request URL DELETE http://accept-project.com/viki/deleteEVAByUID Resource Name Description Parameters userId User ID Required integer Example: 21842
EVA_UID EVA UID to delete Required int Example: 22345
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 94 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: deleteEVAByUID version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png operationSuccessful Value to say is the operation was ok or not Required boolean Example: true Whether the service has already been published or published not Required boolean Example: true author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.5.6 Consumed Services To manage EVA and EDA objects, Viki has to use the KIS interface. The CRUD operations are supported by the KIS Client SDK that is showed in Section 4.10.4.2.
4.5.7 Summary In this section the Visual Wiki component for ACCEPT System and a set of different supporting technologies have been discussed. First, different frameworks to develop REST web services, that allow to store and retrieve AR information from this component, have been analyzed. For this purpose, RestEasy has been chosen. After that, the chapter introduced different tools to provide the translation functionality to the Extended Visual Annotations. iTranslate has been chosen for this functionality. The component structure of the Visual Wiki has been presented in the next section. Next this chapter presented the interfaces to allow the management of AR information, other components of the ACCEPT System and also the permissions. Finally, the consumed services from other ACCEPT components were explained.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 95 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.6 Sensor Abstraction Framework
4.6.1 Overview The Sensor Abstraction Framework (SAF) is a diverse framework that fulfils the crucial task of standardising and distributing sensor data within the ACCEPT system. It is located on the client (SiMaApp & CoOpApp) devices, and communicates with the Profile Nexus (PN), to archive its sensor readings, and the Authorisation Component, to authorise client actions.
4.6.2 Major Design Decision Based on technology specified for related components (SiMaApp and CoOpApp, chiefly), previously specified SAF functionality, and general architectural considerations, these aspects form the basis for the SAF’s technical comparison and selection.
4.6.2.1 Platform and Devices There are two client components that directly utilise the SAF, the SiMaApp and the CoOpApp – a dichotomy of technical decisions will form around these two applications and their respective platforms, even if they use the SAF in a functionally similar manner. Fortunately, both of these clients will utilise devices that run the Android operating system (common Android smart phones being used for the Moverio BT-200), which simplifies and reduces the SAF design decisions related to its platforms. Android is of course an extremely popular, versatile, and well documented operating system, which makes it ideal for the SAF’s purposes. Android exposes its sensors through a Sensor API, providing a well-defined and documented bridge between the actual physical sensors and the SAF (exposed through its plugins).
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 96 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 14: Android Sensor Stack48 The most relevant parts of the Android sensor stack (Figure 14), in regards to the SAF, are the SDK and the HAL. Within the HAL (Hardware Abstraction Layer), each sensor must implement the “sensors.h”49 interface. This interface will determine what data is transmitted from the driver to the SDK. If any new sensors are to be added to the SAF, they’ll need not only a driver, but also an implementation of sensors.h42. The SDK exposes the sensors through various methods and events that the SAF will need to utilize. Virtually every sensor function the SAF implements will begin at this SDK level.
4.6.2.2 Creation and Upkeep of Sensor Profiles on the PN One of the most important decisions of the ACCEPT system, in regards to the SAF, is the creation of Profile Nexus (PN) sensor profiles. This is how the system will keep track of sensor data over periods of time, allowing any number of functions to leverage it. Along with all the other kinds if profiles (user, projects, etc.), each sensor will have its own profile that keeps track of all readings made by the SAF over the duration of its life in the ACCEPT system, as well as other pertinent data, like its ID and type. The PN will contain a living archive of sensor data.
48 https://source.android.com/devices/sensors/sensor-stack.html 49 https://source.android.com/devices/halref/sensors_8h.html D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 97 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.6.2.3 Utilization of Sensor Plugins This is an important decision for solving the problem of scalability in the SAF. The ACCEPT system and the SAF in particular is designed to be modular, allowing for a variety of 3rd party services via the SMP. These services may require their own unique sensors, which is why a plugin architecture is needed. An alternative solution might be to archive purely raw data on the PN, but this would be an unnecessarily space consuming and messy option. With plugins, as soon as the data enter the ACCEPT system it is ready for use. Of course sensors will also have their own low-level drivers, which is a type of plugin in a way, but this is not enough for the ACCEPT system, because the data from the sensor needs to be formatted and retrieved in a standardized way that conforms with the rest of the system. The plugins turn raw data and functions into data and functions that the SAF can use reliably and predictably.
4.6.3 Technology Comparison
4.6.3.1 Frameworks Comparison The selection of the SAF’s software framework will obviously have far reaching effects on all subsequent development efforts. The selection will define the programming language and how the developers access and communicate with different components. Fortunately, because of Android’s adoption rate and its open source Linux kernel, a diverse array of software frameworks have been developed for it, allowing developers to choose the language and libraries that suite their project best. Relevant Android Frameworks: Android SDK50 – The primary development framework for Android, the Android SDK is written in Java and is probably the most robust, efficient way to access Android’s capacities. This framework contains the aforementioned (see section 4.5.1.1) Sensor API, which will be essential to the SAF’s interactions with sensors; even if a different framework is selected, it will need to utilize this API. The SDK also contains tools for building UIs - the developer can either declare UI elements programmatically at run time or separately using XML, or use a combination of these techniques. Being the primary Android framework, the Android SDK is naturally very well documented, and comes with the additional advantage of having its own custom IDE (integrated development environment) - Android Studio. Android NDK51 – The NDK is a toolset that allows the implementation of parts of Android applications using native-code languages such as C and C++. Typically, good use cases for the NDK are CPU-intensive applications such as game engines, signal processing, and physics simulation. The written parts of the program can be compiled to ARM, MIPS or the x86 processor architecture.
50 http://developer.android.com/reference/packages.html 51 http://developer.android.com/tools/sdk/ndk/index.html D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 98 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
One advantage of using the NDK is being able to utilize existing C/C++ libraries. Also, many developers prefer or are more familiar with C or C++. A disadvantage to using the NDK, as opposed to the SDK, is the added complexity of mixing native- code with Java.
Figure 15: High-level Android Architecture and the Relationship between the Android NDK and SDK Xamarin.Mobile52 – Xamarin.Mobile is a library that exposes a single set of APIs for accessing common mobile device functionality across the iOS, Android, and Windows Phone platforms. This increases the amount of code developers can share across mobile platforms, making mobile app development more productive. UI development is uses each platforms native elements, so it’s the same as using the Android SDK. Future plans include notifications and accelerometer services. It is commercially licensed only. Xamarin.Mobile currently abstracts the contacts, camera, and geo-location APIs across iOS, Android and Windows Phone platforms. However, the only sensor that is mentioned in their API documentation is the accelerometer – obviously, this would be a problem for the SAF, which needs access to as much sensor data as possible. However, it’s possible to call actual Java code (implementations of Android APIs) from Xamarin.Mobile’s C# interfaces. Apache Cordova53 – Formerly known as PhoneGap, Apache Cordova is a mobile development framework which enables software developers to build apps for mobile devices using web technologies like JavaScript, HTML5 and CSS3, instead of device-specific languages. The resulting apps are hybrid, meaning that they are neither truly native (because all layout rendering is done via web views instead of the platform's native UI framework) nor purely web-based (because they are not just web apps, but are packaged as apps for distribution and have access to native
52 https://xamarin.com/platform 53 https://cordova.apache.org/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 99 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
device APIs as well as components written for the Android Application Framework). Mixing native and hybrid code snippets has been possible since version 1.9. The differences are just minor between the both frameworks, since PhoneGap wraps Apache Cordova. Cordova has a more expansive collection of sensor and device APIs (referred to as “plugins”) compared to Xamarin.Mobile, but it’s still not exhaustive, making it unideal for the SAF’s purposes. The SAF’s Framework Comparison only has one additional, specific parameter, because the rest of its important parameters are covered by the generic parameters. For example, the parameter “Extensibility” can be thought to include the important aspect of available libraries and extensions of the frameworks. The specific parameters will be: Abstractness / Access Level: Since the main task of the SAF is accessing sensors, it is very important for its framework to have as direct access to them as possible. The SAF is by its nature a low-level component, which has no GUI, and therefore a minimal need for high-level APIs that aggregate multiple functions. For the SAF to have maximum flexibility and power, it needs direct access to Android’s hardware API. Support for Plugin Reflection: Whether or not the framework could accommodate this plugin architecture (see 4.6.2.2). Support for Plugin Web Service IPC: Whether or not the framework could accommodate this plugin architecture (see 4.6.2.2). Support for Plugin Service Broadcasts/Intents IPC: Whether or not the framework could accommodate this plugin architecture (see 4.6.2.2).
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 100 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 27: Frameworks Comparison
Android SDK Android Xamarin Apache Parameter Importance NDK Cordova .Mobile
Generic Parameters
Maturity / Stability / +++ +++ +++ + ++ Quality
Extensibility ++ +++ ++ ++ ++
Open Source / +++ +++ +++ + ++ Standards
Familiarity / Support / ++ +++ +++ + ++ Community
Performance / +++ ++ ++ ++ +++ Scalability
State of the Art ++ +++ ++ +++ +++
EU Project Origin + No No No No
Licenses ++ Open Open Commerical Open Source Source41 Source41 (Annual42) (Apache License 2.043)
Specific Parameters
Abstractness / Access +++ +++ +++ + ++ Level
Plugin Reflection +++ + + + -
Plugin Web Service IPC ++ + + + +
Plugin Service +++ + + + - Broadcasts/Intents IPC
4.6.3.1.1 Technology Selection The Android SDK is the most appropriate choice for the SAF mainly because both clients that will use it will run on Android. If the devices differed in operating system, or if expandability to other mobile platforms was a priority, the Android SDK would not be appropriate, although the Java language itself is versatile enough that the SAF’s logic could potentially be ported to other platforms. Xamarin.Mobile and Apache Cordova would be better suited to cross platform applications. Making direct use of Android APIs lends itself to interaction with the sensors, as this is source of data that every framework must use. It is the most robust and straightforward solution.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 101 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The third-party frameworks for Android mentioned above are designed as solutions to problems and inefficiencies related to working directly with the Android SDK (APIs); however, the SAF simply does not suffer from such problems or inefficiencies, making the frameworks unnecessary at best. If the SAF needed to be cross-platform compatible or if there were existing libraries written in C#, C, or C++ to be used in its development, then one of the aforementioned frameworks would potentially be a better choice.
4.6.3.2 Plugin Architecture Comparison To achieve the SAF’s specific functions its architecture must be carefully designed. Here “architecture”, a rather generic term, refers to the choice and arrangement of the specific services, libraries, and / or interfaces that will constitute the SAF. The specific challenge of the SAF’s architecture is the necessity for its communication between disparate and indefinite components. One of these components is of course sensors—the architectural challenge of sensor integration is being able to incorporate new, unexpected ones dynamically, without making changes to the core logic of the SAF. Another aspect of sensor integration is the contrast between continuous and reactive sensors (the former streaming data at a fixed rate and the latter only returning data on request). The SAF will also need to relay this data to the client components, authenticate client requests, and upload sensor data to the PN. The following architectural styles are those found feasible and relevant to this technological decision. “Inter-process Communication” (IPC) architecture is an umbrella term for any processes that communicate with each other to achieve some task; there are two variations of this architecture feasible for the SAF, as can be seen below: Inter-process Communication o Service Broadcasts/Intents – This solution is the most cumbersome, but perhaps the also the most straightforward. Each sensor plugin would have its own background service in addition to one main SAF logic service that would manage the plugins and their data. The advantage of separating the logic and plugins into their own processes (services) is modularity. With this architectural strategy, plugins would likely broadcast implicit intents (events) to the SAF’s main logic service. o Web Services – On the other hand, the services could implement RESTful interfaces and pass their data through ports, simulating the communication between network components locally. The main disadvantage of these approaches would be their performance overhead, as running individual services is much more intensive than implementing a passive solution. This disadvantage would grow larger and larger as more plugins are added. Additionally, there is the problem of Android’s propensity to close background services at its own discretion. It does so for various reasons, such as to free memory for other services—a solution would have to be developed for this issue. Reflection - Reflection would constitute a more elegant and subtle solution to the SAF’s architecture. Reflection is a capacity of most modern programming languages that allows code to inspect another piece of code dynamically. Java is a
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 102 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
statically typed language, meaning that all data types must be known (via some kind of reference) when the program is compiled. The Java Reflection API bypasses this limitation, enabling the code to interact with code, which lacks a type or reference at runtime. This allows code to be more loosely coupled, a characteristic which is essential to the relationship between plugins and central logic in ACCEPT. The SAF would only need an interface, which prescribes the structure of sensor plugins and a registry of current sensors, enabling it to interact with all the plugins generically. One disadvantage of this approach, though, is its added performance overhead because certain Java virtual machine optimizations cannot be performed on dynamically typed code. In addition, there is a higher need for error handling when using reflection because of its dynamic nature. To compare the different technologies, it decides to use next specific parameters: Complexity: The less complex a solution is, the better, because the collection of plugins will only grow, with the potential to become very large. This parameter is closely related to Performance / Scalability, but with a greater emphasis on how each architecture will affect the other technologies and subcomponents on the device. The architecture should not clutter the system and device. Ease of 3rd Party Adoption: This is perhaps the most important criterion for the plugin architecture, as much of the SAF’s functionality will rely on its flexibility to accept new sensors and each new sensor requires a new plugin (i.e. sensors that are unique from those already existing). A 3rd party interested in using ACCEPT with a new sensor (most likely in combination with a service on the SMP), will need a straightforward, documented process for creating plugins. This parameter overlaps with Familiarity / Support / Community to some degree.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 103 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 28: Plugin Architecture Comparison
Service Web Services Reflection Parameter Importance Broadcasts/ Intents
Generic Parameters
Maturity / Stability / ++ +++ +++ ++ Quality
Extensibility +++ ++ +++ +++
Open Source / ++ +++ +++ ++ Standards
Familiarity / Support / ++ +++ +++ ++ Community
Performance / Scalability +++ - - ++
State of the Art ++ +++ ++ +++
EU Project Origin + No No No
Licenses + n/a n/a n/a
Specific Parameters
Complexity +++ ++ ++ +++
Ease of 3rd Party +++ ++ +++ +++ Adoption
4.6.3.2.1 Technology Selection Reflection has been deemed the most appropriate style of plugin architecture. An inter- process communication architecture is not suited for this component because of the performance overhead disadvantages and Android’s volatile handling of background services. Either a web service or a Broadcast/Intent IPC solution would complicate the development process for both 1st and 3rd party developers. A reflection solution provides the decoupling required of the SAF’s logic and its plugins and does so in an elegant way, with minimal waste of resources. With this selection, the SAF will simply be a Java Class Library (JCL), instead of a service or services, making development simpler. New classes implementing the plugin interface can just be added to a file that the SAF checks for such implementations using reflection. Each plugin will need to implement an interface, and the client applications (SiMaApp and CoOpApp) will need to reference and utilize the SAF’s JCL, which will include methods for subscribing to sensors, requesting sensor data, getting lists of sensors, etc.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 104 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.6.4 Component Structure
Figure 16: UML Component Diagram - SAF
4.6.4.1 Sensor Abstraction The Sensor Abstraction layer is constituted by sensor plugins which utilise the Android HAL (Hardware Abstraction Layer). This HAL is actually accessed through the android.hardware API, part of the Android SDK the SAF will utilise, but it is shown here being accessed directly for the sake of demonstrating the full sensor stack. Every sensor on the device must implement the HAL’s sensors.h interface to interface with the sensor’s low-level driver and be exposed to the high-level API.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 105 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The Sensor Abstraction’s plugins—interfaces themselves—are necessary to interact with the aforementioned HAL interfaces in a useful way. It would be possible to just directly access the HAL via the Framework Logic, cutting out the plugins, but the problem then would be handling different types of data from the sensors. The Framework Logic would have to be adapted to each different kind of sensor, cluttering the logic. With the plugins these adaptations are decoupled from the logic, isolating the work required for new sensors to discrete, standardized interface implementations.
4.6.4.2 Framework Logic This layer is responsible for generating the real value of the SAF, collecting, formatting, and transferring sensor data, while managing registries of subscribed clients and sensors. In a way, this layer does less work than its counterparts in other components because it is mostly a middle man—it will not contain much complex logic, but what logic it does contain must be highly versatile for the various clients and plugins. Sensor Manager – This is the main sub-component for processing sensor data requests and sensor subscriptions. It assimilates and utilizes the other sub- components to execute its tasks. For example, if a client needs data from a certain sensor, the Sensor Manager needs to use functions from the Authorisation Manager to authorise the request and then use the ID included with the request to call the data from the correct sensor. It also has the crucial task of adding new sensors to the Sensor Registry on start up or on request, based on any new plugins available. Sensor Registry – Whenever a new plugin is added to the system, the registry must be updated with a list of all compatible sensors. Likewise, when a plugin is uninstalled, its associated sensors must be deleted from the registry. The registry will have an ID for each sensor as well as other info, such as a sensor type, short description, enabled/disabled status, etc. But the Sensor Registry is not just a simple list for housekeeping type tasks, it is essential to the very architecture of the SAF; because the SAF will use reflection, which eliminates direct references to the plugins at compile time, the only way the Sensor Manager will know which plugins are available is if there is a registry created at run time. Client Registry – This registry keeps track of clients (SiMaApp or CoOpApp) and their subscription to certain sensors. A client subscribes to a sensor if it is a continuous sensor and they want to regularly receive data from it. Clients cannot subscribe to active sensors (sensors that only send data when requested). Authorisation Manager – This component is a kind of surrogate for the central, server based Authorisation Component. Mostly it just relays authorisation requests to the Authorisation Component. Such requests (for sensor data or manipulation) must include an authentication token provided by the requesting client—it is the client’s task to obtain the token (from the Authentication Component). The Authorisation Manager will have the additional task of caching recent authorisations if directly contacting the central server proves to be too performance intensive or slow. Further testing and prototyping will reveal whether caching is necessary. Data Formatter – The Data Formatter will simply be a set of functions that can further refine and process data received from the sensors if necessary. The plugins themselves should handle the initial processing, making the data tenable and
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 106 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
comprehensible, but if further changes need to be made, such as pruning data or combining data, this component can do so. Sensor Listener and Caller – This is the part of the SAF that interacts with sensor plugins. It receives a sensor ID from the Sensor Manager (which itself receives from Sensor Registry or client request) and uses that to call the correct plugin’s function. Since every plugin implements the same interface there are a limited number of functions that can be called. For sensors that broadcast data continuously, this is where the broadcast will be received. The Sensor Manager uses the Sensor Registry to subscribe listeners to sensor broadcasts.
4.6.4.3 Access These subcomponents expose public services to clients dependent on the SAF and allow the SAF to access the Profile Nexus (PN) and Authorisation Component through web services. Authorisation Services – Every time the SAF gets a request from a client for sensor data, it will use these RESTful web services to relay the client’s authentication token and the IDs of the sensors they requested to access; the Authorisation Component will return an answer to the request, either true, false, or an error (e.g. in the case of an invalid token) depending on the user’s privileges, which the SAF should handle. The Sensor Manager waits for this response to find out if it should proceed with the request or do some other action. PN Services – These are similar to the Authorisation Services in that they will be RESTful web services, but their purpose differs. The PN (Profile Nexus) should contain profiles for each sensor; to ensure this, the SAF will attempt to add a new profile to the PN every time a sensor is added to it. Once such profiles are created, every subsequent sensor reading (either by client request or regular, continuous update) will be sent to the PN to keep the profile for each sensor updated and thus keep an ongoing record of all sensor readings. Client Services – Client services are unlike the other services because the clients will implement them and reference them directly, instead of depending on RESTful web services. These will be the publicly accessible functions exposed to clients that include the SAF library in their development. The services will include reading sensors, subscribing to continuous sensors, retrieving a list of current sensors, deleting sensor plugins, and retrieving other info about sensors.
4.6.5 Interfaces
4.6.5.1 Sensor Plugins All sensor plugins will implement a common interface, standardizing the data they can provide to the Framework Logic layer. The sensor plugins themselves must generally rely on the sensors.h41 interface Android uses to expose low level sensors (although it’s possible for a plugin to acquire, and this interface is accessed through the android.hardware46 API, part of the total Android SDK. In many cases, the Sensor Plugin methods are almost identical to the Client Services methods—this is for a few reasons: firstly, most services the SAF provides are derived
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 107 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
directly from sensor access; secondly, both sets of methods are restrained to the methods offered by the android.hardware API; and thirdly, much of the SAF’s practical value is derived from the Framework Logic layer that lies between these interfaces, which will manage, process and assimilate the data in subtle but important ways..
4.6.5.1.1 Subscribe to a Sensor This is the only way the plugin can receive data from a sensor. This should be called at startup if the PN should be constantly updated with the sensor data. Method Name: ReadData Parameters: sensorEventListener: An implementation of the SensorEventListener interface which will listen to sensor changes and call two methods when sensor data changes or accuracy changes (onSensorChanged and onAccuracyChanged respectively). sensorId: Determines which sensor to subscribe to. Must be a sensor that utilizes this plugin. (optional) samplingPeriod: Frequency of sampling desired. (optional) maxReportLatency: Maximum latency of the reports. loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: Boolean, indicating if the subscription was successful. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.2 Unsubscribe from a Sensor Disconnects the plugin from the sensor events. Method Name: Unsubscribe Parameters: sensorEventListener: The listener to unsubscribe the from. sensorId: the specific sensor attached to the listener to unsubscribe. loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 108 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Return Value: Boolean, indicating if unsubscribing was successful. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.3 Get List of Dependent Sensors Users or client apps may need to determine which sensors are dependent on a plugin. Reasons for this include checking dependencies before uninstalling plugins, and troubleshooting sensors. Method Name: ListDependents Parameters: loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: A list of sensors that this plugin interacts with. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.4 Get Sensor Type Fetches the Android-defined sensor type of the sensor. Method Name: GetType Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 109 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
A standard Android sensor type, such as TYPE_PRESSURE or TYPE_HEART_RATE, or null if the sensor type is not defined. . Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.5 Get Range Fetches the range of values the sensor can possibly produce. Method Name: GetRange Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: The maximum and minimum values of the sensor, or null if the sensor does not support this function (likely in the case of external sensors). Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.6 Get Reading Delay The maximum and minimum time that a continuous sensor can delay its readings. Method Name: GetDelay Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 110 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The maximum and minimum possible values of the sensor’s delay, or null if the sensor does not support this function (likely in the case of external sensors). Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.7 Get Description Method Name: GetDescription Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: A short, succinct description of the sensor’s functionality and purpose, or null if the sensor does not support this function (likely in the case of external sensors). Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.8 Get Hardware Info Fetches the version and vendor information of the actual physical sensor hardware. Method Name: GetHardwareInfo Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: The vendor name and version of the sensor, or null if the sensor does not support this function (likely in the case of external sensors). Error Handling:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 111 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.9 Get Power Usage Fetches the expected power consumption of the sensor when it is being used. Method Name: GetPower Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: The power in ma used by the sensor when in use, or null if the sensor does not support this function (likely in the case of external sensors). Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.1.10 Get Reporting Mode Fetches the reporting mode, an important piece of info for understanding how the sensor functions. Method Name: ReportingMode Parameters: sensorId: indicates which sensor should be checked (must be associated with this plugin). loginToken: a unique token generated by the Authentication Component which the Authorisation component can use to determine if a use to identify a user and determine if their login is valid and current. A token is generated each time a user signs in on a client app. Return Value: The reporting mode of the sensor: either continuous (sensor reports at a regular interval), one-shot (sensor deactivates itself after sensing something once), or on change (reports whenever the values of its reading change). Error Handling:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 112 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
SAFException if any error arises. Permission Needed: eu.accept.saf.PLUGIN_READ
4.6.5.2 Client Services When a client includes the SAF package in its code, these are the functions they can expect to have access to. The Client Services include the most primary functions of the SAF, like retrieving sensor data and getting a list of sensors.
4.6.5.2.1 Get Sensor Data Asks the SAF to make a sensor reading and return the data. The SAF will also upload the reading to the PN to update the sensor profile automatically. Method Name: ReadData Parameters: sensorId: Determines which sensor to read data from. Return Value: A Sensor Data Object, with properties for the data itself and its type. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.INFORMATION_READ
4.6.5.2.2 Subscribe to a Sensor When a client requires a constant stream of data from a sensor, they need to subscribe to it. Method Name: Subscribe Parameters: sAFEventListener: An implementation of the SAFEventListener interface which will listen to the SAF for sensor events sensorId: Determines which sensor to subscribe to. (optional) samplingPeriod: Frequency of sampling desired. (optional) maxReportLatency: Maximum latency of the reports. Return Value: Boolean, indicating if the subscription was successful. Error Handling: SAFException if any error arises. Permission Needed:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 113 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
eu.accept.saf.INFORMATION_READ
4.6.5.2.3 Unsubscribe to a Sensor Allows the client to unsubscribe from a sensor they previously subscribed to. Method Name: Unsubscribe Parameters: eventListener: The listener to unsubscribe the from. sensorId: the specific sensor attached to the listener to unsubscribe. Return Value: Boolean, indicating if unsubscribing was successful. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.INFORMATION_READ
4.6.5.2.4 Get List of Sensors Simply fetches all sensors currently installed (with a plugin) in the system. Method Name: ListSensors Parameters: (optional) plugin: find only the sensors dependent on this plugin. Return Value: A list of currently installed sensors (of the type specified if specified). Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.INFORMATION_READ
4.6.5.2.5 Get Sensor Info Clients can learn various info about sensors that may be useful for various tasks. Method Name: GetInfo Parameters: sensorId: Determines which sensor to return info about. Return Value:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 114 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
A Sensor Info Object, with properties that describe the sensor, like installation data, its associated plugin, and its maximum polling frequency. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.INFORMATION_READ
4.6.5.2.6 Get List of Plugins This service is the same as “Get List of Sensors,” except that it lists plugins instead. Method Name: ListPlugins Parameters: (optional) sensor: find the plugin this sensor utilizes. Return Value: A list of all currently installed plugins, or the installed plugin a sensor uses. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.INFORMATION_READ
4.6.5.2.7 Add New Plugin A client app can add new plugin interface implementations by providing a JAR containing the plugin, which may have been downloaded from the SMP. The SAF will check if the plugin is already installed and if it is valid. Method Name: ListPlugins Parameters: pluginJar: a JAR (Java Archive) containing one or more new plugins. Return Value: A message listing which, if any, plugins were successfully installed. Error Handling: SAFException if any error arises. Permission Needed: eu.accept.saf.INFORMATION_WRITE
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 115 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.6.6 Consumed Services The primary task of the SAF is to relay sensor data to client components in various useful ways, but it also relies on a few other components for auxiliary functions. It relies on the Profile Nexus to update sensor profiles appropriately; the SAF simply sends a Sensor Data Object containing all pertinent info about the sensor, as well as its data, to the PN, where the PN should find the relevant profile (or create a new one) and update it properly. As for authentication and authorisation measures, the SAF relies on each client component to supply a login token with each request, which is itself generated by the Authentication Component. It then uses that token to authorise any client action by sending it to the Authorisation Component, which will then be responsible for verifying the user’s login, comparing their privileges to their request, and returning a response to the SAF. Lastly, the SAF also consumes the android.hardware API’s services, but these are of course not part of ACCEPT. Everything the SAF does with sensors is constrained by this API.
4.6.6.1 Authorisation Services The SAF will rely heavily on the Authorisation Component, because almost every function the SAF exposes to its clients’ requires certain permissions, determined by the action, the user, and the sensor. These authorisation services will be provided over the AMF and implemented by the client apps that actually receive and convey these requests to the necessary components.
4.6.6.1.1 Authorise Sensor Action SAF actions will be grouped into access levels, like READ and MODIFY. Each sensor and user combination will have its authorised access level. For example, a user may be able to read data from one sensor, but not another, while the opposite might be true of another user. The SAF will expect a Boolean (yes/no) response from the client when given an action type, a sensor, and a user (login token). ACCEPT Components used: The clients, CoOpApp (chapter 4.3) and SiMaApp (chapter 4.2).
4.6.6.1.2 Authorise Framework Action This function applies to all client functions that do not relate directly to specific sensors. This could include for example adding a new plugin or getting a list of all plugins. Just as with the previous service, the SAF will expect a Boolean (yes/no) response from the client when given an action type, a sensor, and a user (login token). ACCEPT Components used: The clients, CoOpApp (chapter 4.3) and SiMaApp (chapter 4.2).
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 116 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.6.6.2 Profile Nexus Services The SAF is responsible for uploading any sensor data requested from a client to the PN— these services will provide that functionality. As with the authorisation services these services will be services relayed through the client apps.
4.6.6.2.1 Upload Reading The most basic and frequent interaction between the SAF and PN; Every time a sensor makes a reading (by request or continuously), the SAF will simply send the PN an object containing all pertinent info about the reading and the sensor, allowing the PN to archive the data in its proper buckets. ACCEPT Components used: Profile Nexus (chapter 4.8) and the clients, CoOpApp (chapter 4.3) and SiMaApp (chapter 4.2).
4.6.6.2.2 Get Sensor Profile The correlative of the “upload reading” function—the PN should return some kind of profile object when requested and provided with a user login token with the required permissions. The SAF can then relay the info to a client. ACCEPT Components used: Profile Nexus (chapter 4.8) and the clients, CoOpApp (chapter 4.3) and SiMaApp (chapter 4.2).
4.6.7 Summary The SAF is somewhat simpler than most other ACCEPT components, but it is a crucial source of data for the whole system, so its technical selections are equally crucial. The simplicity of the SAF is due to it having no “moving parts,” figuratively speaking—it is only a library of functions and interfaces, not an active, independent process. Since it is just a library, making its functions modular and expandable are paramount. The framework selection was made easy by the fact that all client apps (where the SAF will be used) will run Android. Knowing the component’s platform ahead of time obviously eliminates many technical concern—hence the Android SDK’s selection as the SAF’s framework; without the need to build GUIs or access functions across multiple platforms, the features of other considered frameworks are superfluous. The Android SDK’s hardware API provides maximum and direct access to the device’s sensors, which is the primary concern of the SAF. The plugin architecture was a more interesting decision, however, like with the previous selection, the selection of Java Reflection was based on minimalism. Both options—IPC and Java Reflection—could handle the needs of the SAF, but adding independent processes when the same thing could be accomplished with no processes would be unwise because of performance, complexity and reliability concerns 4.7 Autonomous Messaging Framework This section defines the major decisions made for implementing AMF along with the public interfaces and interaction patterns.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 117 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.7.1 Overview Autonomous messaging framework (AMF) is a conduit that tires up together all participants of the ACCEPT system from legacy data sources and business services to users interacting with the system via hand-held devices. ACCEPT system belongs to the realm of Internet of Things and knowledge intensive systems. There is a profusion of independent services and data sources that reside on various platforms spanning from legacy monoliths to tablet PCs and wearable devices such as glasses, helmets that support augmented reality. ACCEPT is going to capitalise on the existing well established standards used in the construction industry for decades (now referred as level 1-2 of BIM) and explore the new levels of BIM that include so called 4D and 5D views. The legacy nature of many of the involved systems such as CAD/SCADA, ERP, CRM, HR, etc. also means that those systems most of the time do not have Web Service interface and cannot communicate via HTTP protocol. They also need transformation of their messages, since they often talk in custom built and complex XML formats, EDI/EDIFACT, iDoc, XLS, SQL, and many other dialects incompatible to each other. Integration with legacy and off-the-shelf monolith systems is important because tons of valuable data are already there and those systems are tightly integrated into the construction business processes and they will not be replaced anytime soon. At the moment, there are two major paradigms for enterprise application integration competing on the market, namely, Service-Oriented Architecture (SOA) and REST. The former one is built on top of the Enterprise Service Bus (ESB) integration pattern, functional decomposition, SOAP messages, and star topologies. It is usually associated with large upfront investments in IT infrastructures in terms of time and funds. In contrast, REST integration style capitalizes on the existing Web infrastructure. It supports P2P communications, lightweight protocols and message formats, and it does not require large upfront investments especially when combined with the microservices paradigm. The success and rapid growth of the Internet is often provided as a proof for opting for the REST style. REST web services are used by many large players such as Amazon, eBay, Netflix to name just a few, for delivering new business functions fast (sometimes within a few days) through exploiting existing polyglot infrastructures along with a decomposition of functionality and delivering this functionality in form of single purpose applications often called microservices. Both of the approaches facilitate the loose coupling (time and availability aspects, location transparency, asynchronous calls) of communicating components if done right, but SOA can outreach sources and services outside of HTTP boundaries that is not possible for REST Web Services, because RESTful integration is done using HTTP as a transport and application protocol. Thus, it cannot communicate over other protocols such as TCP, SMTP, JMS, IIOP, etc. where traditional SOA has all its merits. In addition, modern tools for enterprise application integration such as TIE Smart Bridge supports also integration via HTTP paving the road between two worlds.
4.7.2 Major Design Decisions Communication infrastructure will be based on a message bus component, which is responsible for all communication between AMF components. The major decisions to take into account selecting the underlying technology are explained in the following points: D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 118 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Components within the AMF are loosely coupled and can use different technologies, e.g. Java, .Net, Python, etc. For this reason, the communication bus between them has to be able to support completely heterogeneous services and formats. The most reasonable choice for such communication bus implementation is to follow the Enterprise Service Bus (ESB) paradigm that supports both Service- Oriented Architecture (SOA) and its extension Event-driven SOA (SOA 2.0 or SOA+). The latter extends traditional SOA with the ability to use events in the inter- component communication. The necessary features of the communication bus are basic routing and forwarding of messages, multi-recipient message broadcast (when the same message is sent to several recipients in topic), provisioning of durable queues with the possibility to temporarily retain data (for both queues and topics), and finally it should be possible to communicate synchronously as well as asynchronously. For collecting statistics about data interchange, which very valuable for the parties using Business Intelligence tools for getting more insight about their business, the communication bus should be able to create Audit Logs of the communication activities. For the user interaction with the communication bus (of, e.g., system administrators), it should have a Graphical User Interface (GUI) that can support all daily tasks like monitoring of the system, management and configuring of services and components, viewing system logs. Interactions between components based on different technologies and data transformations between various formats have to be orchestrated by the bus. Orchestration planning is usually done using a workflow designer for creation of custom workflows for the bus’s execution engine. Custom communication protocol handlers and data formats need to be supported by the bus via a mechanism of plug-ins.
4.7.3 Technology Comparison As the most appropriate technological foundation for the communication bus within AMF needs to be selected from an array of existing offerings, first, a comparison among the most promising ones has been carried out. In addition, areas where the product analysed has to meet AMF specific requirements are identified and difficulty of adapting the product to these requirements is weighted in. The following technologies have been selected to as candidates for the communication bus implementation: JBoss ESB54 is an open-source ESB based on Apache Camel, Apache CXF and Apache ActiveMQ. With these technologies, JBoss ESB provides reliable messaging, routing, implementation of enterprise integration patters, RESTful web services and a robust SOA infrastructure based on Java Business Integration (JBI). JBoss ESB supports multiple options for connecting to external applications with connectors for JDBC, HTTPS, SalesForce, Twitter, etc. It also supports dynamic configuration and management allowing deploying or updating of services across nodes while the ESB is running. In addition, it allows for an easy integration with
54 https://www.jboss.org/products/fuse/overview/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 119 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
heterogeneous environments hosted anywhere. Finally, its development environment is based on Eclipse and provides support to users through of a community and forums. AMF implementation based on JBoss ESB needs significant involvement of Java specialised developers and many PMs. WSO2 ESB55 is an open-source ESB based on SOA pattern design and released under the Apache License v2.0. WSO2 ESB supports all the most important transport protocols (HTTPS, POP/IMAP, JMS, etc.), variety different formats (JSON, XML, SOAP, WS, EDI, etc.) and adapters to cloud services (e.g., Salesforce, PayPal, LinkedIn, Twitter, JIRA, etc.). However, the number of connectors is comparatively limited to other technologies. WSO2 ESB supports key features like routing of messages, logging and auditing. It enforces and manages security centrally, including authentication and authorisation mechanisms via security protocols such as WS-Security, LDAP, Kerberos, OpenID, AMFL, XACML. WSO2 is highly concurrent solution (up to 2,500 concurrent connections on standard hardware, without dropping messages) and horizontally scalable via clustering. Finally, this technology contains an advanced web interface for managing and monitoring activity and analyzing performance statistics. AMF implementation based on WSO2 ESB needs significant involvement of Java specialised developers and many PMs. TIE Kinetix SmartBridge (TSB)56 is a complete ESB integration platform focused on supporting SOA architecture and based on the latest .NET technology. TSB supports reliable and multi-recipient messaging, data transformations and service orchestrations. It exchanges messages using required communication methods and its underlying message queues can temporarily store messages. By default, it supports the majority of used communication protocols such as HTTP/HTTPS, SMTP/POP/IMAP, XMPP, etc. but the TSB also offers the possibility to extend these protocols via add-ins. All TSB activity is recorded in the internal logs, providing better overall control and reliability. For to managing services and monitoring activity and statistics, TSB has a rich user-friendly web user interface built using .NET technologies (ASP.NET MVC357 and MonoRail58). TSB is a scalable solution that can be extended with more advanced functionalities. Building on TSB means using a complete solution, which is hosted by TIE and involves fixed timing and pricing, including support. Message transformations are defined in so called “mappings” that can be created and managed using TIE Smart Integrator - a result of FP6 project STASIS. Mappings can be created without involvements of software developers in the graphical way, which increases the productivity and decreases the time to market. TIE Semantic Integrator (TSI) is a powerful semantic-based format characterisation, mapping and transformation tool that allows mapping definitions to and from different data sources in formats like XML, XSD, RDF, Flat Files (FF), CSV, EXCEL, Databases (MS SQL 2008/2012, MySQL). The goal of TSI is to provide intelligent automatic mapping suggestion based on smart semantic algorithms and vocabularies. TSI creates and manages semantic relationship
55 http://wso2.com/products/enterprise-service-bus/ 56 http://tiekinetix.com/nl/tie-kinetix-smartbridge 57 http://www.asp.net/mvc/mvc3 58 http://www.castleproject.org/projects/monorail/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 120 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
between entities, which conform to its Logical Data Model (LDM). Each schema format (XSD, EXCEL, RDB, FF, RDF) imported into TSI is first transformed to an internal neutral reusable format based on the LDM meta-model. Further transformations use data from that format. TSI is a solution written in the Java programming language, which provides a state-of-the-art user interface to import, define mappings and transform data, improving the overall usability of the tool. The user interface is based on the Graphical Modelling Framework (GMF) from Eclipse using Standard Widgets Toolkit (SWT) for GUI representation. Mapping suggestions between elements of source and destination data formats can be auto- generated based on semantic algorithms, and these mappings can be persisted and be re-used or shared. Building on TSI means using a complete solution, which is provided by TIE and involves fixed timing and pricing, including support. Mule Anypoint59 is the complete platform that lets companies realize business transformation through API-led connectivity. It is a unified, flexible integration platform that solves the most challenging connectivity problems across SOA, SaaS and APIs, in a low-friction, developer-friendly way. Anypoint Platform lifts the weight of custom code and delivers the speed and agility to unlock the potential of this Connected Era. Implementation based on Mule Anypoint needs significant involvement of Java specialised developers and many PMs.
59 https://www.mulesoft.com/platform/enterprise-integration D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 121 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Mule Parameter Importance JBOSS ESB WSO2 ESB TSB/TSI Anypoint
Generic Parameters
Maturity/Stability/Quality +++ + + +++ +
Extensibility +++ ++ ++ +++ ++
Open Source / Support of + ++ ++ N/A (TIE is ++ Standards owner)
State of the art +/- YES YES NO YES
Performance / Scalability +++ + + ++ +
Familiarity/ Support / + ++ ++ - (TIE has + Community knowledge)
Licenses ++ LGPL v2.1 Apache 2.0 TIE License Commercial
EU project synergies + NO NO YES (TSI) NO
Specific Parameters
Cost of ownership + +++ +++ +++ +
RESTful integration +++ ++ ++ +++ ++
Legacy systems integration + ++ ++ + ++
Reliable Messaging / + + + ++ + Receipt Acknowledgement
Secure communication +++ ++ ++ ++ + protocol
Message queues / topic +++ ++ ++ +++ ++ queues
Multi-recipient-messaging +++ +++ +++ +++ +++
Provide configuration UI for +++ NO YES YES YES component
XML, CSV, RDF supported +++ XML, CSV, XML, CSV, +++ XML, JSON, Java, EDI, Java, EDI, EDI, CSV JSON, JSON, YAML YAML
Database, Web Service +++ YES YES YES YES access supported (database via Apache Camel)
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 122 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 17: ESB (Enterprise Service Bus) technologies evaluation From the above comparison if seems likely that TIE Kinetix SmartBridge ESB (TSB) meets the majority of requirements as compared with the competing technologies that appear less fit as a candidate for the implementing the communication bus component. The main conclusions are: In the comparison table one can see that all compared technologies are pretty much similar in both specific and general parameters. However, TSB stands out in the sense of maturity and overall stability, which can be confirmed by its track record of offering services to more than 2000 TIE customers for more than five years and across different countries, and having demonstrated overall reliability in production environment. As a commercial core product of TIE, TSB is constantly worked on and its updates are provided on monthly basis, which can contribute to the reliability and secure stability of the AMF, this is in contrast with open-source products that have less defined update cycle and own product goals. TSB works in a cluster of several servers, which form the commercial integration environment of TIE. This allows for greater scalability compared to offerings of competitors. For this reason, the stable and scalable infrastructure needed for the AMF can be implemented easily, as the TSB is already prepared for such configuration. TIE’s SmartBridge meets the set project criteria for fitting the requirements and will be adapted to provide the communication backbone of the AMF and extended to implement the missing features.
4.7.4 Technology Selection AMF will be built on top of the existing commercial product of partner TIE – TIE SmartBridge (TSB). TSB is a commercial product, which allows connections to the most popular legacy systems (SAP, AS2400, Allegro, GXS). TSB is able to receive data, transform them and send them to another system through number protocols and interfaces available (JMS, XMPP, HTTP, SMTP, FTP, etc.). New features for TSB that are required by the ACCEPT project need substantial work since a lot of requirements are pushing TIE into direction of Internet of Things, which was not before the TIE’s domain. But this is also the exact reason why TIE is interested in the project: TIE is looking forward to adding the necessary functionality to its comprehensive stack of Integration Brokerage acknowledged by Gartner60 in order to penetrate new markets and being able to offer its customers more connectivity options. To strengthen the EU project synergies, AMF will reuse the STASIS way of semantic mappings using TIE Semantic Integrator (TSI), the product TIE has built based on the outcomes of the STASIS project, and which will lay ground for the AMF Gateways. Being a product used in company’s business, TSI has a user-friendly user interface, which is enriched with many features helping the user to define the mappings between source and destination data structures in order to transform that data. It supports many kinds of
60 http://tiekinetix.com/nl/nieuws/tie-kinetix-recognized-in-inaugural-gartner-magic-quadrant-for-integration- brokerage D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 123 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
transformations and data formats, which include XML, CSV or RDF among others. TSI used another internal TIE product Mapping Repository for storing of mappings, so that they can be used for data import or transformations. In the comparison of the specific parameters in the previous section, one can see that TSI provides a unique feature, not existing in the competing technologies, which are semantic mappings. This allows creating of mapping in semi-automated way, where mapping between different formats are suggested based on the link likelihood weights, and the user can accept the suggesting or discard it. In addition, TSI’s rich user interface stands out of competition, providing unmatched usability and user experience. TSI is fully integrated with TSB, which is already selected for the communication bus implementation, and this tight coupling provides fully operational semantic and data interoperability framework for the AMF. While being a great fit for the needs of the project, the following features specific for ACCEPT need to be added to the TSB: Project specific RESTful and WebSocket endpoints Service registry and discovery module New workflows New API need to be added to the TSB kernel to support 3rd party developers who want to build their own tools on top of TSB monitoring/audit part AMF has to support the WebSocket protocol connections in addition to REST. WebSocket is a protocol providing full-duplex communications channels over a single TCP connection. It is designed to be implemented by web browsers and web servers, but it can be used by any client or server application. More interaction between a browser and a web site is made possible by providing a standardised way for the server to send content to the browser without being solicited by the client, and allowing for messages to be passed back and forth while keeping the connection open. These features of WebSocket allow for optimal streaming of video and audio data, and its support need to be added to TSB. Mapping Repository is an internal TIE product used for storing transformation mappings and relations between them and their customers. In addition, it provides extended search functionality, like full text search. This data storage is durable and scalable. Being built on extensible architecture, Mapping Repository supports easy extension of the mapping format used, thus being easily adaptable for the project needs. Using the TIE SmartBridge it is possible to define complex data import workflows. Management and monitoring of these workflows can be done using the web-interface of TSB, and execution can be started manually or scheduled to be initiated by the TSB.
4.7.5 Component Structure The communication bus of AMF will use TIE Smart Bridge (TSB) which is highly efficient message exchange and routing as well as service integration platform. In addition to message dispatching and service integration, it can perform data transformation on the fly. Being an Enterprise Service Bus (ESB) by design, it has been built with high performance and reliability in mind. The main building technologies of TSB are: MS SQL Server is used for temporary data storage for message transfer in addition to transaction logs and as persistent storage for certain queues
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 124 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Windows Workflow Foundation is used in the GUI for configuring of workflows that orchestrate the components of the platform and data flows MS WCF (Windows Communication Foundation) for exposing TSB via Web Services
Figure 18. TIE Smart Bridge Architecture The Gateway components of the AMF will be built on top of several other technologies: TIE Semantic Integrator (TSI) for importing and linking data from 3rd party systems by creating mappings between data formats A Web GUI for managing imports Mapping Repository to store mappings A web scraping module for extracting data from various web-based sources For the implementation of integration functionalities TIE Semantic Integrator (TSI) has been chosen. Being a mature and reliable product, it will add unique semantic mappings and transformations features to the AMF together with its rich user interface for managing this functionality. The graphical editor for mapping definitions will be based on that of TSI and the Mapping Repository will provide its own web-based UI.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 125 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.7.6 Interfaces This section provides a technical overview of the following major categories of interfaces that AMF exposes to outside for integration and management purposes: Gateways, including WebServices / RESTful Service registration and discovery API Mappings and transformations Workflows Cloud base archiving The access points (front-end) will be implemented as a RESTful APIs but also it is necessary to support a full-duplex communications via HTML5 WebSocket. Since currently the exact application/domain communication protocol is not yet elicited the first implementation will support a 1st level RESTful interface, i.e. one URL that can accept all major HTTP operations such as GET, POST, PUT, DELETE, HEAD, LINK, UNLINK and appropriate response codes (2**, 3**, 4**, 5**) following best practices. Commands and queries need to be encoded inside the payload of each communication method. Metadata can be also used for the defining certain non-functional criteria of each communication act, e.g. timeout, priority, etc. Along the course of the project when understanding of type of queries will be more understood via usage and examples the API will gradually mature as well and migrate towards higher levels of maturity according to Richardson’s Maturity Model for HATEOAS. The REST interfaces will be discussed in this Section 4.7.6, whereas protocols and data formats will be described in Section 4.7.7. Describing the REST interfaces, every service method is presented in a separate table, where a detailed description, the URL and request parameters are given along with a possible invocation example and the method response types.
4.7.6.1 Gateways AMF Gateway components gather data from external sources. They allow integrating these sources together that is implement strategies of retrieving that external data, transforming it to the required format and then passing along to another component connected to the communication bus. Gateways are written in such a way that they can be executed within the same memory space as TSB and that natively connect with the system on the other side supporting specialised protocols and APIs, providing high communication speeds and convenience. The examples of such gateways are MS SQL gateway, SAP XI gateway. A Gateway: Defines mappings between source and destination data formats and stores these mappings in the Mapping Repository for possible subsequent reuse Imports or links data into the AMF from third-party data sources Extracts data from external sources, e.g. arbitrary web-sites or data sources in yet unforeseen formats, by implementing custom API wrappers, for example, for web- scrapping.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 126 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.7.6.1.1 Interface “listQueues” The RESTful interface “listQueues” (Table 29) retrieves a list of queues and topics available on the communication bus, which contains all information needed for subscribing to any of these listed queues or topics. Table 29: RESTful Interface Description – Get a List of Queues and Topics List Services and Topics Description Interface to get a list of queues and topics on the communication bus Request Request POST api/listQueues:filter/ URL Resource Name Description Parameters filter JSON object with the filter parameters. Type Required Object can be “queue” or “topic” Example: { “componentName” : “KIS”, “type” : “topic”, “description”:”building1” } Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 500 Error during processing JSON template JSON object with the answer. Attributes JSON Object Example: { “Queues” : [ { “componentName” : “KIS”, “type” : “topic”, “description” : “building1 topic” },
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 127 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ “componentName” : “KIS”, “type” : “queue”, “description” : “building1 queue” } ] } JSON Error JSON Object Example: { “errors” : [ { “errorId” : 1, “description” : “Invalid parameters” } ] }
4.7.6.1.2 Interface “subscribeQueue“ The RESTful interface “subscribeQueue” (Table 30) allows a component to subscribe to queue or a topic to receive messages. The XML structure of a message is described in Section 4.7.7.2.2. Table 30: RESTful Interface Description – Subscribe to a Queue or a Topic Subscribe to a Queue or a Topic Description Interface to subscribe to a queue or a topic Request Request POST api/subscribeQueue:subscriptionInfo/ URL Resource Name Description Parameters subscriptionInfo XML document. Required Object Example:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 128 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 500 Error during processing JSON template JSON object with the answer. Attributes JSON Object Example 1: { “Id” : 1, “description” : “Successfully subscribed” } Example 2: { “Id” : 3, “description” : “The requested queue was not found” } JSON Error JSON Object Example: { “errors” : [ { “errorId” : 1, “description” : “Bad request” }
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 129 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
] }
4.7.6.1.3 Interface “unsubscribeQueue” The RESTful interface “unsubscribeQueue” (Table 31) is used to unsubscribe a component from a previously subscribed queue or topic. The XML structure of the message is described in Section 4.7.7.2.3. Table 31: RESTful Interface Description – Unsubscribe from a Queue or a Topic Unsubscribe form a Queue or a Topic Description Interface to unsubscribe from a queue or a topic Request Request POST api/unsubscribeQueue:subscriptionInfo/ URL Resource Name Description Parameters subscriptionInfo JSON object with the filter parameters. Required Object Example:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 130 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“description” : “Successfully unsubscribed” } Example 2: { “Id” : 3, “description” : “The requested queue was not found” } JSON Error JSON Object Example: { “errors” : [ { “errorId” : 1, “description” : “Bad request” } ] }
4.7.6.1.4 Interface “sendMessage” The RESTful interface “sendMessage” (Table 32) is used to send messages to a queue or a topic. It uses the AMF Component Message structure defined in Section 4.7.7.2.1. Table 32: RESTful Interface Description – Send a Message to a Queue or a Topic Send Message to a Queue or a Topic Description Interface to send a message to a queue or a topic Request Request POST api/sendMessage:messageDestination/ URL Resource Name Description Parameters messageDestination XML Structure. Required Object Example:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 131 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 132 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“errorId” : 1, “description” : “Bad request” } ] }
4.7.6.2 WebSocket Interface WebSocket is a special protocol allowing dull-duplex communication via a single connection. After establishing the connection using an HTTP request and receiving an upgrade of the protocol, the subsequent messages can be exchanged via this connection with a very little overhead. Among other features, this enables higher message throughput compared to the plain HTTP. For this reason for performance sensitive data transfers, like audio or video data, WebSocket can be a better choice than HTTP. WebSocket communication if based on asynchronous message streams. WebSocket does not require the recipient to acknowledge receiving of the message and combined with the reduced of the overhead as compared to the traditional HTTP, WebSocket can be described as a lightweight protocol. The protocol uses standard HTTP ports, therefore helping traverse firewalls. In some conditions, especially exchanging large continuous streams of data, like audio or video, the communication bus (TSB) will act as a proxy between the sender and the receiver of data, operating via WebSocket on both ends. This will be achieved by developing a special WebSocket connector for TSB that allows components to connect to it via WebSocket. Both communicating parties will connect as clients to a URL on the TSB side. Based on the provided authentication data, the TSB WebSocket connector will check the pairing rules whether these clients are allowed to communicate with each other and then will upgrade the protocol to WebSocket and will start relaying messages between these two paired connections as if they were a single connection. To use the WebSocket facility, the following interface can be used.
4.7.6.2.1 Interface “establishWebSocketConnection“ The RESTful interface “establishWebSocketConnection” (Table 33) allows a client to open a WebSocket connection with the TSB. Initial HTTP request will be upgraded to a WebSocket connection upon successful authentication of the caller. TSB will apply pairing rules configured internally to allow this client to communicate with another WebSocket client connected to the TSB. After the WebSocket connection has been established, the participating parties are free to exchange data in the format they like. This data format is not altered by the TSB. If the client wishes to finish the WebSocket session, it can simply drop the connection. Table 33: RESTful Interface Description – Establish a WebSocket Connection Establish WebbSocket Connection
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 133 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Description Interface to establish a WebSocket connection to the TSB Request Request POST api/establishWebSocketConnection:authDetails URL Resource Name Description Parameters authDetails JSON document. Required Object Example: { "authDetails": { "username”: "user123", “password”: “password123” } } Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 401 Unauthorized 500 Error during processing
4.7.6.3 Service Registration and Discovery API Service registry integrated with the TSB allows parties to publish services accessible via the communication bus and discover these services to make use of them. The service registry provides facilities for the following roles: Service provider: creates a service (or a component) and publishes its interface and access information to the service registry. They assign a category to that service, so that is can be found using search functionality. It also lists all the potential service recipients. Service consumer: locates entries in the service registry using specially designated methods and then binds to the service provider for invoking one of these discovered services. While service consumers can use specialty exposed REST interfaces to locate and invoke services, the service providers have to register their services using the TSB GUI (Graphical User Interface). The REST methods for locating and consuming services are described below.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 134 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.7.6.3.1 Method “listServices“ The RESTful interface “listServices” (Table 34) allows obtaining a list of services available in the AMF that fulfil the given filter criteria. The data returned will contain all information necessary to communicate with the selected service (or component). Table 34: RESTful Interface Description – List Services List Services Description Interface to get a list of services available in the AMF. Request Request GET api/listServices:componentFilter URL Resource Name Description Parameters componentFilter JSON object with the filter parameters. Required Object Example: { “componentName”: “KIS” } Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 500 Error during processing JSON template JSON object with the answer. Attributes JSON Object Example: { “components”: [ { “componentName” : “KIS”, “services” : [ { “serviceName” : “addEntry”, “parameters”:[‘param1’,‘param2’] },
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 135 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ “serviceName” : “deleteEntry”, “parameters”:[‘param1’,‘param2’] } ] } ] } JSON Error JSON Object Example: { “errors”: [ { “errorId” : 1, “description” : “No services found” } ] }
4.7.6.3.2 Method “invokeService“ The RESTful interface “invokeService” (Table 35) is used to invoke one of the services registered in the service registry of TSB and located with the “listServices” method. Table 35: RESTful Interface Description – Invoking a Service Send Message Component Description Interface to invoke a service. Request Request POST api/invokeService:serviceParameters/ URL Resource Name Description Parameters serviceParameters JSON object with the service parameters. Required Object Example: { “componentName” : “KIS”, “serviceName” : “addEntry”,
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 136 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“parameters”: [‘param1’,‘param2’] } Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 500 Error during processing JSON template JSON object with the answer. Attributes JSON Object Example 1: { “id” : 1, “description” : “Error invoking service” }
4.7.6.4 Mappings and Transformations Transformations between data formats occurring inside the TSB are based on mappings that define the way the data has to be transformed. Mappings are normally designed visually using the GUI of the TSI (TIE Smart Integrator), which is a part of TSB. These mappings are then stored in the Mapping Repository. The Mapping Repository is an internal TIE product built on the Google Cloud technologies and designed as a specialised data storage for mappings with extended search capabilities. The mapping definitions are stored together with their descriptions and other metadata. The Mapping Repository implements its own data storage and search facilities so that it can share and synchronise data with the TSI. The search functionality of the Mapping Repository is based on Elasticsearch, which is able of performing complex full text search queries on mappings and their attachments. This search module allows searching mappings and their metadata using any property of the mapping or metadata. It is possible to search using keywords and define groups of data to limit the search scope. For example, one can search only for mappings suitable for the given customer that transform data from XML to EDI. The mapping repository provides a separate REST interface for developers to access its features. Several of these REST interfaces are exposed to be used within the ACCEPT project.
4.7.6.4.1 Method “findMappings” The RESTful interface “findMappings” (Table 36) is used to search all available mappings that fulfil the search filter criteria.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 137 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 36: RESTful Interface Description – Find Mappings Find Mappings Description Finds mappings in the Mapping Repository that match the query provided. Request Request GET api/findMappings:searchFilter URL Resource Name Description Parameters searchFilter JSON object with the filter parameters. Required string Example: { “mapType”: “EDItoFFS”, “mapVersion”: “1.2” } Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 500 Error during processing JSON JSON Object JSON object with the importations. Attributes Example: { “mappings”: [ { “mappingId”: 1, “description”: “Mapping 1”, “mappingFile”: “map1.jse”, “inputFormat”: “XML”, “outputFormat”: “FFS” }, { “mappingId”: 1, “description”: “Mapping 2”,
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 138 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“mappingFile”: “map2.jse”, “inputFormat”: “XML”, “outputFormat”: “FFS” } ] } JSON Error JSON Object Example: { “errors”: [ { “errorId”: 1, “description”: “Mapping not found” } ] }
4.7.6.4.2 Method “uploadMapping” The RESTful interface “uploadMapping” (Table 37) allows to upload a new mapping to the Mapping Repository. Table 37: RESTful Interface Description – Upload Mapping Upload Mapping Description Uploads a new mapping to the Mapping Repository. Request Request URL POST api/uploadMapping:mappingInfo Resource Name Description Parameters mappingInfo JSON object with the mapping definition. Required string Example: { “mappingFile”: “map1.jse” } Response HTTP Status Value Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 139 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Code 200 The request was successful 400 Bad Request 500 Error during processing JSON template JSON object with the response. Attributes JSON Object Example 1: Successfully uploaded { “code”: 1, “mappingId”: 1, “description”: “Upload successful” } Example 2: Error { “code”: 2, “description”: “Could not upload the mapping” }
4.7.6.5 Workflows and activities The core of TIE SmartBridge (TSB) is the translation and modification of data: for example, TSB can unclutter document batches for multiple recipients into properly grouped document stacks, translate from one document type to another, modify document properties, etc. In other words, TSB can make ‘sense’ from data that were previously nonsense to the intended recipients. In order to deliver data in a form that the recipient requires, one will need to prepare and modify the data that enters TSB. In almost all cases this involves creating a chain of data modifications and/or translations, which is called a Workflow. With a Workflow one prepares and modifies incoming data to produce the output that the recipient requires. A Workflow is an executable set of instructions, which will prepare or modify data in such a way that it fits the requirements of the parties that will receive the data. For each document that TIE SmartBridge receives, it will look for a relevant Workflow, so that the applicable set of instructions is executed on the document, and appropriate output is produced. TSB exposes the following workflow REST interface to be used within the ACCEPT project.
4.7.6.5.1 Method “listWorkflows” The RESTful interface “listWorkflows” (Table 38) allows to list all workflows created by the given user. Table 38: RESTful Interface Description – List Workflows List Workflows
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 140 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Description Interface to list all workflows of a user registered in the AMF. Request Request GET api/listWorkflows:filter URL Resource Name Description Parameters filter JSON object with the filter parameters. Required Object Example: { “userId” : 1 } Response HTTP Status Value Description Code 200 The request was successful 400 Bad Request 500 Error during processing JSON template JSON object with the workflow definitions. Attributes JSON Object Example: { “workflows” : [ { “workflowId” : 1, “name” : “Workflow 1”, “description” : “Workflow definition 1” }, { “workflowId” : 2, “name” : “Workflow 2”, “description” : “Workflow definition 2” } ] } JSON Error JSON Object Example:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 141 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ “errors” : [ { “errorId” : 1, “description” : “Workflows not found” } ] }
4.7.6.6 Cloud Base Archiving TIE E-Archiving is secure document archiving software. It automatically encrypts documents being transmitted via the communication bus and safely stores them a password-protected location, either locally or in the cloud. It is possible to recover these document form the E-Archive using the built-in search functionality, and conveniently review document information regardless of its original format. The architecture of the TIE E-Archiving is shown in the Figure 19.
Figure 19 Architecture of the TIE E-Archiving Solution E-Archiving is available as a cloud solution, and as a standalone on premise solution. As a standalone application TIE E-Archiving can be added to any stack that uses recent Windows versions. However, using it together with TIE SmartBridge will enable you to show its full potential.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 142 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Its main features are: Store secure and immutable versions (password protected, encrypted and hashed). Support for 3 means of storage, even simultaneously in any combination: o Local storage. o Microsoft Azure cloud storage. o Amazon S3 cloud storage. Automatically delete documents after a configurable amount of months, on a per archive basis. Search for archived documents based on the following document properties; Archive name, envelope number, document format, document type, document subtype, document number, sender, recipient document date. View human readable versions of the documents. While not directly exposing REST interfaces, the E-Archiving solution participates in the audit and monitoring part of ACCEPT, allowing the system administrators see what data has been exchanged and when. In addition, this is used by the developers of the project for debugging purposes.
4.7.7 Protocols and Data Formats TSB is based on .NET and requires a specific Windows environment to run in. However, all other components communicate with TSB using standardised and widely used protocols and therefore can be based on any architecture or written in any programming language. All components in ACCEPT are loosely coupled and do not depend on each other. For this reason, AMF is also independent and does not need any other component to run, however other components will use AMF for communication, data transformations, service discovery, etc.
4.7.7.1 Protocols Components what want to communicate within the AMF framework components mainly use HTTP, HTTPs and REST protocols. However, TSB additionally supports a variety of other communication protocols. These are described below: HTTP(s): Hypertext Transfer Protocol (HTTP) allows requesting and transmitting files, especially web pages and web page components, over the Internet or other computer networks. The secure version (HTTPS) is a combination of the Hypertext Transfer Protocol together with the SSL/TLS protocol, which provides encryption and secure identification of the server. REST: Representational state transfer (REST) is a type of software architecture, which is focused on using the HTTP and XML standards for the transmission of data. The operations can be invoked using GET, POST, PUT and DELETE methods, therefore it does not require special implementations to consume these services. Additional benefit is that it makes it possible to use JSON instead of XML as the data container. SOAP: Simple Object Access Protocol (SOAP) is a standard protocol that defines how two components in different processes can communicate through the
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 143 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
exchange of XML encoded data, its operations are defined as in WSDL (Web Services Description Language). XMPP: Extensible Messaging and Presence Protocol (XMPP) is a communication protocol for message-oriented middleware based on XML (Extensible Markup Language). SMTP: Simple Mail Transfer Protocol (SMTP) is an Internet standard for electronic mail (e-mail) transmission. IMAP: Internet Message Access Protocol (IMAP) is a protocol for e-mail retrieval and storage, an alternative to POP. IMAP allows multiple clients simultaneously connected to the same mailbox. S/MIME: Secure/Multipurpose Internet Mail Extensions is a widely accepted protocol for sending digitally signed and encrypted messages. S/MIME allows for encrypting emails and digitally signing. FTP: File Transfer Protocol is a widely used network protocol for transferring computer files from one host to another host over a TCP-based network. TSB can also provide secure FTP (SFTP). X.400 / P7: The P7 protocol allows a mail user agent to send and receive messages through an X.400 message store and the X.400 MTS. In a sense, it is alike the Internet IMAP protocol, providing the possibility to manage messages within the message store, rather than having to download them locally. GXS: Managed File Transfer Service enabling the secure, reliable exchange of large files. Oftp: Odette File Transfer Protocol was developed to offer a standard communication platform, used mainly in the European automotive industry. The protocol is very efficient, allowing large transmission windows to be utilised while allowing to resume transfers, providing data compression and security.
4.7.7.2 Format Messages, which are exchanged within the AMF, are represented in standardised formats, based on XML, and parts of data in these messages are used by TSB for message routing and other operations, like transformations.
4.7.7.2.1 AMF Inter-Component Message The AMF messages, exchanged between components, have to follow the XML structure below:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 144 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 20: AMF Inter-Component Message
4.7.7.2.2 AMF Subscription Message For subscribing to a queue or a topic, a message in the following format can be used:
Figure 21: AMF Queue Subscription Message
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 145 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 22: AMF Topic Subscription Message
4.7.7.2.3 AMF Unsubscription Message For un-subscribing from a queue or a topic, a message in the following format can be used:
Figure 23: AMF Queue Unsubscription Message
4.7.8 Summary In this section, the major design decisions have been detailed and the technology that will be used for AMF implementation has been discussed. TIE’s SmartBridge ESB and its companion integration product TSI have been selected as the foundation for the communication bus, as meeting all most important requirements while comparing different technologies, in addition to excelling in several of them as compared to the rest of the competition. TSB will be adapted to support currently missing features required by the project. Finally, different interfaces, protocols and formats provided and supported by the AMF have been discussed. In conclusion, ACCEPT AMF is going to be built on top of the proven technological basis, yet adding to the stack specific innovative features that are required by new wave of devices, services and infrastructures.
4.8 Profile Nexus
4.8.1 Overview Profile Nexus (PN) implements a part of BIM that is important for ACCEPT project context. In ACCEPT BIM is understood as an information service that contains information about 2D, 3D models, costs, human resources, tasks, materials, “as-built” information, quality aspects and is capable of answering questions about all those aspects seamlessly to the requester (human or machine). PN consists of four distinctive parts, namely “Project
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 146 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Workflow Profile”, “Project Construction Profile”, “Project User Profile”, and “Project Quality Profile”. One construction project is described by these four profiles. ACCEPT platform can process many projects at the same time. The information models for each profile are described below in this section. Information models are updated from sensors, user devices, architect tools (e.g., AutoCAD, Revit, etc.), legacy systems and other information resources. Those profiles provide a basis for an open set of business services that are capable of creating reports for humans and machines, for answering queries about the project status any point in the past, progress and open tasks and many more (see Figure 25).
Figure 25. Profile Nexus Overview Each profile is responsible for carrying on a part of Profile Nexus. Together they form a complete current state of the project. Profile Nexus can also answer requests about the status of the project in the past. When possible each profile is responsible for providing REST resource-based interface for accessing (read-only) information and specific APIs for commands that require business logic and updates on the models. Information is exchanged in form of domain events distributed via messaging mechanisms. Profiles will be explained in the sufficient details in the dedicated sub-sections of this chapter.
4.8.1.1 Major Design Decisions Usage of Lambda Architecture61 as an architectural pattern for this component Usage of CQRS (Command Query Responsibility Segregation)62 as basis for the system design
61 https://en.wikipedia.org/wiki/Lambda_architecture 62 http://martinfowler.com/bliki/CQRS.html D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 147 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Usage of event collaboration for design of communications and state updates Lambda Architecture (LA) is a type of generic, scalable and fault-tolerant data processing architecture, based on the experience implementing distributed data processing systems at companies like Backtype and Twitter. The LA aims to satisfy the needs for a robust system that is fault-tolerant, both against hardware failures and human mistakes, being able to serve a wide range of workloads and use cases, and in which low-latency reads and updates are required. The resulting system should be linearly scalable, and it should scale out rather than up. CQRS helps segregate operations that read data from operations that update data by using separate interfaces. This pattern can maximize performance, scalability, and security; support evolution of the system over time through higher flexibility; and prevent update commands from causing merge conflicts at the domain level.
4.8.1.2 Technology Comparison As have been described before Profile Nexus is a set of loosely coupled services (that carry on data or business logic) that communicate via messages (events) through communication channels. This design has been deliberately chosen in order to facilitate the parallel delivery of individual components. Components of the Profile Nexus are free to choose their own technologies, however, the suggested technologies for gluing these components together are listed below: Repository with complex logic (e.g., triple stores with SPARQL) Spring XD as a general framework for data processing OpenSourceBIM Server63
4.8.1.3 Technology Selection This section is different from the same sections for other components for the reason that Profile Nexus is a set of loosely coupled components. It merely suggests technologies that may be used for the gluing different parts together.
63 https://github.com/opensourceBIM/BIMserver D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 148 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Sesame/ Spring XD OpenSourceBIM Parameter Importance OpenRDF
Generic Parameters
Maturity & Stability +++ + + +++
State of the art +++ ++ ++ +++
Open Source & standards +/- YES YES YES
Extensibility +++ +++ +++ +++
Performance / Scalability +++ ++ ++ +++
Familiarity & Support & + + + +++ Community
EU Project Origin + +/- +/- +/-
Licenses +/- MIT MIT MIT
Specific Parameters
Performance +++ ++ + +++
Coverage of ACCEPT +++ + ++ +++ requirements
Profile Nexus will be built as an infrastructure for loosely coupled services communicating via messages that supports extendibility and openness of the platform. Each service/sub- component then will be implemented with the most suitable technology. For instance, Project Construction Profile is an integration of the CYPE tool tuned for ACCEPT and KIS from Ascora. Thus, Profile Nexus consist of design decisions and key elements such as queues, service registries, cloud deployment environments such as Google Compute and Google App Engine.
4.8.2 Information Data Model
4.8.2.1 Overview In order to guarantee an agile, flexible and efficient coordination of the construction process as well as ensuring high quality of work execution, the PN manages information, interacts with data model across four profiles (project workflow profile, construction project profile, user profile and quality profile), and updates data, when it is triggered by an event- reaction data mining system. The Information Data Model (IDM) creates a foundation for nexus services that act as a central point for the mediation between different profiles and the rest of the ACCEPT system.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 149 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.8.2.2 Major Design Decision The IDM will provide a data structure to support the following functionalities of each profile: Project workflow profile: a) provide all relevant information related to tasks and subtasks; b) support an efficient coordination of construction works by providing list of tasks and by actualizing current status of tasks and providing alert/notification about any problems occurred during the work execution ; b) provide workflow for scheduled tasks and/or subtasks on construction site in order to support installation process of building components and materials according to the rules of the trade; c) assign crews to a specific task and to a specific location (where task has to be performed); d) synchronize supply side s with construction process in terms of just- in-time deliveries. Construction project profile: a) provide construction project documentations such as: plans, sections, elevations, 3D model, construction details (BIM and CAD software for construction details); b) provide information and/or documentation about technologies, components, materials, and other project documents (i.e. technical specifications). Quality profile: a) provide quantitative and qualitative parameters that inform about the quality of construction works during the whole construction process, e.g. in terms of energy-efficiency (conformity between as planned and as built); b) provide quantitative parameters related to the productivity on construction site (i.e. task progress, time deviations, etc.). Project user profiles: provide user profiles of the stakeholders involved in the construction process. According to u user rights a user has an access to different information of the ACCEPT system. Furthermore, a user receives notifications and alerts referred to construction tasks, construction progress and quality of works performed on construction site. The concept of the IDM is visualised using the ER-Diagram (the general view of ER– Diagram is in Annex). The main entities, attributes and relationships have been defined in the ER-Diagram. The entities of each profile and their relationships are established based on the functionalities identified in User stories (T.2.4, T2.5) as well as User Cases (T2.1), which reflect real needs of stakeholders involved in the construction process. The entities of different profiles interact with each other creating processes that support functionalities of the ACCEPT system. In the ER-Diagram, entities coloured in blue belong to the Project Workflow Profile, in green to the Construction Project Profile, in yellow to the Project User Profile and in violet to the Quality Profile. This IDM can evolve in the WP5, when specific tasks dedicated to each profile will start. Furthermore, based on this IDM a mock-up of the SimaApp was done. The mock-up is only an example how the ACCEPT System might look like and work. It may change during the project.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 150 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.8.2.3 Theoretical Data Structure The IDM provides data structure to support the following processes within the four profiles of the PN: Project Workflow Profile: The Project workflow profile (PWP) supports an efficient coordination of the construction process and ensures high quality of work execution. Separate parts of PWP are described below. 1. Creation of task list, component and material inventory: The data regarding the project scheduling are imported form BIM software (4D and/or 5D - if feasible) or other construction management software (e.g., MS Project, Sablono, etc.) using Data Abstraction Layer (DAL) component. In these process four entities, their attributes and relationships are mapped: “Task”, “Subtask”, “Component” and “Material”. The first entity (“Task”) is referred to main task (i.e., foundation works), which can be composed of various subtasks (e.g., formwork positioning, concrete casting, waterproofing, etc.). The “Component” and “Material” entities are linked to a subtask. BIM software allows to import this kind of data framework because a single subtask is related to building components and its materials. Data referred to tasks, subtasks, components and materials will be reported to the following inventories “Task List”, “Component List”, “and Material List”, respectively. Furthermore, each task and/or subtask can be defined by the temperature dependency (i.e. task cannot be performed, when the outside air temperature is too low or too high). Since sensors on site will monitor the weather parameters, a user can be informed if weather condition is not ideal to perform a task.
BIM 5D Software BIM 5D
Export IFC to Export data to (format tbd) Export IFC to
DAL DAL
Import data
Import data
Import data Subtask Priority Tag Priority Tag ID/Code ID/Code Task Cost Cost (H,M,L) (H,M,L) Quantity Quantity Cost ID
Company Unit of Unit of Company Quantity measure measure Component Task Is of Subtask Is of Component Create List Task List Create Unit of Work hours Technical measure Import data Technical Description Description To tal work Technical Technical hours Description Company Installation Start an d Data Guideline finish Date Task ID Dependency has Type (Hard, Has Has Dependency Soft) Start and Relationship Dependency Dependency finish Date (S-S; F-F; S-F) Type (Hard, Relationship Soft) (S-S; F-F; S-F) Cost ID Technical Quantity Data Unit of Temperature Temperature measure °C | F Dependency Material Create Material List
Type of ID Technical dependency Description Installation Guideline Ta sk ID Company Inventory of Tasks | Components | Materials Figure 26: Data Structure for the Creation of Task List, Component and Material Inventory
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 151 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 27: Data Framework for Task, Components and Materials Each entity gets the following attributes: “Task” and “Subtask”: ID; Name; Technical Description; Start and finish date; Total span of working hours for a task; Number of subtask; Quantity; Unit of measure; Cost; Responsible company for work execution; Dependency Type (task should be determinate by hard (mandatory) or soft (discretionary) dependency); Dependency Relationship (Start-to-Start, Finish-to-Start, Finish-to-Finish, Start-to-Start); Task Priority (type of priority: low, medium, high). “Temperature Dependency”: ID; Type of dependency; Temperature (°C, F). Task or subtask should get the temperature dependency, if required, in order to inform user in advance about any conflict between task to perform and external weather condition. “Component” and “Material”: ID; Name; Technical Description; Quantity; Unit of measure; Cost; Manufacturer, Task ID (to which task this component/material belongs), Installation guidelines. 2. Definition of construction area and its assignment to a task: The “Construction Area” is connected with the construction project profile because it has to retrieve information on construction area such as ID, Level, Sector, Unit, Room, etc. to indicate workers where a specific task has to be performed:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 152 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
2D 3D Model Drawings
Has Has
Sector Unit
Level Room Task
Construction ID ... Area
Li nk to Subtask
Construction Area
Figure 28: Data structure for the construction area 3. Definition of crew, timespan for a work as well as its assignment to a task In this process, the creation of a crew is related to the Project user profile since it retrieves data on workers. A user (e.g., site manager) is able to create a crew by selection of workers within the presence list. Once a crew is created, it is assigned to a task or to a subtask as well as to a timespan that indicates a specified timeout period for task’s completion. The following entities and their attributes are mapped in this process: “Worker”: ID; Name; Acronym; Skills; Contract type (part time, full time, etc.), Rating of the worker. “Presence List”: it can be created from the worker’s database (Project user profile), which the following information on selected workers: Acronym, Name and Number of working hours. This list is needed to create a crew afterwards. Moreover, it is possible to assign the attribute of foremen (who is going to be a foreman) within this list. “Crew”: ID, Name of a crew, number of selected workers. “Timespan”: defines a timeout period for task’s completion for a crew by Start day, month, year and End day, month, year.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 153 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Task Subtask
Assign to Assign to Start End Year ID Year Name Start Day Total Crew Assign time to Timespan working No. of hours selected End Day Define a workers Worker Start End Acronym Month Month Presence List Worker Nr of Name working ID hours Foreman Name assign worker to Worker Rating Description
Contract Skils Acronym Type
Definition of crew and of time span for a task
Figure 29: Data Structure for the Definition of Crew, Timespan for a Work and Crew Assignment to a Task 4. Creation of a task workflow:
Task Subtask
Link to
Link to
Add workflow to Workflow List Name Notes Date Updated Crew Acronym ID Created by Create notification Date Approved when workflow is created Workflow Informati User Participants Assign to Has Status Date (Template) Dratf on
Involved Name Task or Notification Subtask List User
Define steps in
Start and Send notificatio to involved users end day Date Name Name Document Nr of AMF days ID Is a Is a Update status, alert and alert description (Sub)task Activity Steps Control when control (Check list) is done list Alert Alert Status Description Update status, alert and alert description Report Alert when control (Check list) is done Status Type Alert Assign rule to Description Create
Parallel Date Time of activities Rules reminder
Linear Involved Reminder Information activities User Send reminder to involved users to do checklist
AMF Workflow Figure 30: Data Structure for the Creation of a Task Workflow The task workflows in the ACCEPT system can be implemented in two different ways: a) by attachment of installation guidelines or manuals referred to building components/materials or b) by creation of task workflows. The final solution has to be
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 154 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
still agreed with user partners. Below is described an example of task workflow creation. The task workflow provides detailed activities that have to be fulfilled by worker during a task or a subtask in order to complete construction works according to the rules of the trade and energy requirements. Each task workflow is attached to a task and/or subtask. The “Task Workflow” entity is defined by “Steps” entity, which is composed of two elements needed to create a workflow: “Activity” and “Control”. The “Activity” entity is defined by the following attributes: a) Name of activity; b) Number of day needed to perform this activity; c) Task or subtask Name to define to which (sub)task the workflow belongs; d) Start and end day (this data is automatically provided when (sub)task is selected); e) Document (to attach technical specification about work execution); f) Alert to inform about eventual problems; g) Alert Description; h) Status to indicate a status of an activity (done, work in progress, delayed, etc.). The “Activity” entity can be defined by a set of rules: parallel activities, linear activities. The “Control” entity is defined by the following attributes: a) ID; b) Name; c) Type (type of check that has to been done, i.e. DC – Delivery Check, CC – Consistency Check, AC – Activity Check, IC – Installation Check); d) Alert to inform about eventual problems on site; e) Alert Description; f) Date (when the check has to be done); g) Status (i.e. done, not done, done but some problems occurred, etc.). Furthermore, a reminder is sent in advance to involved users in the workflow in order to do a check using checklists provided by the quality profile.
Figure 31: An Example of Workflow and its Actualization by Reporting Process in the Quality Profile
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 155 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
5. Creation of report list by collecting check lists: The report process will support controlling of construction progress and construction quality using checklists. This process is composed of the following entities: “Report List” and “Report”. The report list is linked to “Task List” entity, since reports refer to a specific task. “Report” entity consists of “Component report” and “Material report” that can have at least three checklists (Consistency, delivery and installation checklist) as well as of Task Checklist to report a real effort put in task completion. These checklist are fulfilled by a user (i.e. worker, foremen or site manager) on construction site (see more in the Quality profile).
Report List
Collect repots in
Collect Report Collect Collect
Component Task Check list Material Report Report
Collect
Collect
Consistency Delivery Installation Consistency Delivery Installation Checklist Checklist Checklist Checklist Checklist Checklist Figure 32: Data Structure for Report List Quality Profile: The Quality Profile (QP) monitors and synthetizes information about the quality of the building components and the productivity of the building construction process. The QP works with three main sources of data detailed below. Firstly, the QP processes data from the project workflow profile. The QP queries the project workflow profile to compare the “as_planned” and “as_is” (or “as_built”) information related to scheduled duration of task, and queries the construction project profile to compare the “as_planned” and “as_is” information regarding the energy performance of components, materials. With these, it will be able to compute different metrics about components/material mismatches as well as about the timing of the different tasks. Secondly, the QP processes Quality Checklists. At different stages of the construction process, quality checklists have to be filled in by workers or by quality controllers. These checklists contain important information about different aspects of the quality of work execution, energy performance of components/materials that are verified by user on construction site. The meaning (semantic) of these checklists is known by the QP, so that it can aggregate relevant checklists to provide high-level metrics (for example to the dashboard). The Information Model required for these Quality Checklists comes in two parts: the checklist templates on one hand and the many individual answers to all the checklists on the other hand. Within the QP the following checklist can be provided to users: a) Tasks Checklist to control the quality of work execution, to measure a real effort needed to complete this task as well as to update the current task status (i.e. task in progress, task delayed, etc.); b) Installation Checklist to verify if components were installed correctly; c) Delivery Checklist
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 156 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
to verify if construction materials/components has been delivered to construction site; d) Consistency Checklist to verify if delivered materials/components match to requirements of “as planned” project (i.e.: U-vales, conductivity, thickness, etc.). Thirdly, the QP monitors sensor data. The QP is able to receive single data or streams of data from sensors. It can compare these data with ‘expected values’ and trigger a warning notification in case of unexpected incoming values. It also stores these sensor data to be able to ‘review’ them (as values or graphs) for future investigation or correlation with other quality metrics. The information processes by QR can be visualized, for instance, on Dashboard providing significant KPIs related to the energy performance of building envelop and construction process. Furthermore, any inconsistency with as-planed project will be point out and a notification will be sent to a user.
Task Workflow Data from the Activity Task Subtask Data from the Project Project Workflow Construction profile (as- Update when control Update subtask status profile (as- (Check list) is done planned) Steps Update task status Report List planned) Productivity KPIs Visualize data on Control Update when control Retreive as-planned data (Check list) is done
Retreive as-planned data Report Dashboard Collect data
Analyse and provide KPIs Provide data from checklists (as built) Quality Metric
Building Quality Visualize data on KPIs
Name Retreive data from sensors
ID Task ID / Subtask ID Collect Data Crew Name Collect Data Task Name / Date Subtask Name Component Task Checklist Material Report Sensor Data SAL Has Report Problems Description Location Deley causes Photo Effort
Task status Real Completed Update Report Update Report working Update Report Sensor hours Work in Delayed Update Report progress
ID Date ID ID Data to Date Crew verify Data to Name verify Delivery Installation Consistency Has status Has status Checklist Checklist Checklist Date Match Problem Crew Crew Dismatch /Note Data to Name Has status Name description Problem verify If not installed/installed description Photo Consistency with problems, inform user Status If delayed, Delivered ID inform user If not valid inform user Dismatch ID Delivered Not Installed but but Delivery Status installed problems problems
Installation User Profile Installed ID Delay Ordered Status User Profile User Profile Quality Check Figure 33: Data Structure of the Quality Profile Construction Project Profile: The Construction Project profile (CPP) creates a construction project, which is composed of the following information: 3D building model, 2D drawings (plans, sections, and elevations), components, materials, construction details (2D), project documents and installation instructions. The information related to 3D building model as well as to 2D drawings are imported from BIM software (IFC standard) via DAL. It is possible to obtain 2D plans, sections, elevations, metadata of components and materials from the 3D BIM model. Since all construction details are mostly designed in 2D CAD software, the possibility to import, for instance .dxf format, should be guaranteed by DAL. All other formats related to documents (i.e. PDF) can be uploaded to the ACCEPT system. Furthermore, data referred to components and materials can be collected within an inventory (“Component List” and “Material List”). Finally, the CPP provides data to Viki.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 157 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Component Material List List
create create ID External Viki Cost ID Cost Source Technical Quantity Quantity Data Unit of Technical measure Upload file (PDF, Word, etc) Description Component Material Unit of measure
Technical Name Date Task ID Technical Project Company Installation Description Installation Data Documents Guideline Guideline Task ID Ty pe Company ID Created by Elevation Section Provide Date data to Name ID ID Date Plan Created by Type 2D 3D Model Date Construction ID Drawings Type Created by Details Type Created by Name Has Installation Date Has Instructions Has Longitude Latitude Altitude Type Construction ID Created by project has geographical coordinates Georeferencing Project Type of projection
Rotation Import Data Construction Project
Refer to Refer to DAL
Import data from Import data from
BIM 5D CAD Software Task Subtask
Figure 34: Data Structure of the Construction Project Profile According to the ER-Diagram the following entities and their attributes are mapped: “2D Drawings”: ID; Name, Date, Type, Plan, Section, Elevation, Created by (it specifies who is responsible for this data) “3D Model”: ID, Name, Date, Type, Created by “Construction details”: ID, Name, Date, Type, Created by “Georeferencing”: Longitude, Latitude, Altitude, Rotation, Type of projection (The association of the project (3D building model) with location in physical space is important for a correct visualization of the building model in augmented reality) “Project documents”: ID, Name, Date, Type, Created by (Documents uploaded to the CPP can be linked to a task, subtask or a specific task workflow) “Installation Instructions”: ID, Name, Date, Type, Created by (Instructions uploaded to the CPP can be linked to a task, subtask, components, materials or a specific task workflow) “Component” and “Material”: ID, Technical description, Technical data (e.g., insulation material: thickness, thermal conductivity, density, specific heat capacity, etc.), Quantity, Unit of measure, Cost, Company (manufacturer) that provides a components/materials, Installation guideline (if available). “Component List” and “Material List” are inventory of components and materials respectively and are related to task/subtask. Project User Profile: The Project User Profile (PUP) provides user profiles of all stakeholders involved in the construction process, which contain the following information: personal information, skills, duties, and user location on construction site. Each user profile can have the following add-ins: a) calendar to see availability, task engagement (e.g., worker), report illness day,
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 158 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
etc., b) notification to get information on relevant events on construction site, to communicate with other stakeholders, etc.; c) alerts to report a problem on construction site (problem can be related to construction works, construction progress and quality). Furthermore, user profile is set up according to user rights in order to personalize GUI of a user and provide him/her access to selected information of the ACCEPT system. Finally, users can report their location if the CoOpApp device (smart glasses) is worn by them. When the device is used on site, the location data are collected and are stored in the “Location” entity.
Based on user rights, a user profile can access information in other profiles Project Workflow Site Project profile Manager Manager
Access to Is a Is a Architect Supplier Is a Is a Project Stakeholders create User Profile Access to Construction Is a profile Engineer Is a External Is a Is a expert Access to
…. General Contractor Quality profile
Skilles Calendar Location
Personal Information Notifications CoOpApp Duties Alerts Device Employment Data Location Sensor Project User Profile Figure 35: Data Structure of the Project User Profile
4.8.3 Construction Profile
4.8.3.1 Overview The Construction Profile is the application, which allows the extraction of selective information from the Building Information Model. This application will import and manage the data needed in the ACCEPT System from BIM models as geometry, location and other information. The Construction Profile will run as a desktop component within the ACCEPT System. This information shall be provided for a specific purpose. In that sense the provided information has to correspond to the data exchange requirements set by such specific tools. As an output the BIM filtering services provide model views that are subsets of building data models and that contain the selected information for a specific application. This output can take different kind of formats according to the type of information filtered and to interoperability constraints existing because of the existing interfaces between the different tools.
4.8.3.2 Major Design Decision Open standards and true non-proprietary interoperability are key to the long and short term success of the building industry as it moves forward with BIM processes and technology.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 159 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Open standards for BIM are seen as the vehicle to achieve data interoperability and the integration required for improvements in the construction sector’s efficiency and productivity. The hypothetical condition requires that “the electronic data exchange, management, and access are fluid and seamless. This implies that information needs to be entered into electronic systems only once, and then it is available to all stakeholders instantaneously through information technology networks on an as-needed basis”. For this to occur within our landscape of a multitude of proprietary solutions and file formats, a common standard based on open standards is needed. In order to achieve data interoperability and seamless data exchange between the tools included in the ACCEPT framework and their native data structures, we will rely heavily on the BIM paradigm. Data exchange will be addressed thanks to the IFC standard and XML files. The IFC standard provides an excellent reference model along with numerous domain extensions and nowadays has become the leading standard for exchanging data between BIM platforms. It is reflected by the high number of supporting software64 (CAD, FM, model checking, toolboxes, etc.).
4.8.3.3 Technology Comparison Open standards for BIM tend to be misunderstood as either exclusively related to IFCs (Industry Foundation Classes), yet another software platform, or that IFC just does not work. The reality is that the IFC open standard schema is more complete than any other proprietary schema. What remains is to have the latest IFC4 version fully implemented and certified into current proprietary software solutions. Although the IFC schema is still evolving, the barrier to use has typically been vendor implementation within the proprietary product. The IFC data specification will be evaluated in comparison to the gbXML65 (Green Building XML) standard with respect to the related available tools (e.g. for data storage, retrieval, mapping) and the specific ACCEPT requirements. In addition, a parallel or complementary utilisation of both standards will be examined and eventually implemented. The Green Building XML schema (gbXML) is an open schema developed to facilitate the transfer of building data stored in Building Information Models (BIM) to engineering analysis tools. gbXML is being integrated into a range of software CAD and engineering tools and supported by leading 3D BIM vendors. gbXML is streamlined to transfer building properties to and from engineering analysis tools to reduce the interoperability issues and eliminate plan take-off time. The Industry Foundation Classes (IFC) data model is intended to describe the building and construction industry data. It is a platform neutral, open file format specification that is not controlled by a single vendor or group of vendors. It is an object-based file format with a data model developed by buildingSMART (formerly the International Alliance for Interoperability, IAI) to facilitate interoperability in the architecture, engineering and construction (AEC) industry, and is a commonly used collaboration format in Building Information Modeling (BIM) based projects. The IFC
64 http://www.buildingsmart-tech.org/implementation/implementations 65 http://www.gbxml.org/currentschema.php D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 160 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
model specification is open and available. It is registered by ISO and is an official International Standard ISO 16739:2013. Extensible Markup Language (XML) is a simple, very flexible text format derived from SGML (ISO 8879). The following specific parameters are defined: 3D model capacity: The technology must be able to connect the 3D building model with the most of BIM-oriented software. In addition, this technology has to be recognised by the most of the agents and standards. Constructions parameters: The technology must contain all the information in the design phase and the construction phase. Also must link the construction parameters to the 3D model. User profiles Information: The technology have to improve the ACCEPT tools with all the information of the users involved in the construction phase. Project phases information: The technology must contain the 4D, 5D phase information to improve the gap between the design and the construction phases. Table 39: Construction Profile Technology Comparison
Parameter Importance IFC gbXML XML
Maturity + Stability + Quality +++ +++ ++ ++
Extendability +++ ++ + ++
Open Source + Standards +++ +++ ++ ++
State of the art +/- +++ ++ +++
Performance + Scalability + +++ + ++
Familiarity + Support + ++ ++ ++ ++ Community
Licenses + +++ +++ +++
Specific Parameter
3D model capacity +++ +++ ++ +
Constructions parameters +++ +++ + ++
User profiles Information +++ +++ + +++
Project phases information +++ ++ + +++
4.8.3.3.1 Technology Selection
A BIM model includes many different kinds of data, but ACCEPT will need just a part of it. The Exchange Requirements in ACCEPT will be specified with the help of the Information
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 161 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Delivery Manual (IDM) methodology established by Building SMART and they are expressed as a result in a tabular form. In order to automate the data filtering process those Exchange Requirements are implemented in so-called Model View Definitions (MVD) that specifies the needed data in a language that can be computed by a machine. Indeed an MVD can be created in different ways, for example, as a file or simply as a query, but it then needs to be computable by a machine through a dedicated tool like the IFC Manager. For standardization purpose BuildingSMART introduced the possibility of using mvdXML that is an XML based MVD format. It is more usual for information to be exchanged about a particular topic and the level of detail provided to be driven by the project stage. This is a matter of deciding which IFC components should be used to meet requirements of ACCEPT components. This is important both for users and for solution providers.
Figure 36: Information Delivery Manual. Guide to Components and Development Methods’ by Building Smart
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 162 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 37: Picture from ‘Information Delivery Manual. Guide to Components and Development Methods’ by Building Smart
4.8.3.4 Component Structure
Figure 38: Construction Profile sub-components Construction Profile layer has four components: Project Documents: where all information is stored, in any form, related primarily to the construction elements. Details: It is the graphical detail information about one of the building blocks. This information is usually in dxf, pdf or jpg format. These two subcomponents are referenced from the 3D model and will be stored in the KIS component. 3D model: This sub-component provides BIM-filtering services that are part of the core services in the ACCEPT System to organize and manage the needed information into the Profile Nexus which will feed the rest of the project components. In this context, two services are needed to perform the Construction Profile. On one side, the generic filter layer included on the IFC Manager reads and executes MVDs for allowing, on the other side, to represent a basic 3D model viewer called IFC Builder. This tool will represent in graphical way the information included in the IFC file of the project. It also allows the possibility of developing a new model at this
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 163 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
point so we could open a new way of defining new models. The 3D model structure is composed by two elements to manage correctly the BIM model information: o IFC Builder used to receive, manage, and translate the information IFC2x3 into IFC4 and eventually to modify the 3D model. This option offers also the possibility of starting modelling the project at this point. This tool can visualize the IFC from each specialist. For example, the building services from the MEP Engineer. o IFC Manager, used to manage the whole entities of the BIM model and identify their geometrical properties. All this information needs to be organised in order to be properly read and managed in each step of the process. This application can manage any type of format file (pdf, dxf, jpg, etc.) to connect the information from the design phase (project documents and details) to the construction phase. This way it is possible to filter what information is need for the different components of the ACCEPT System. Georeferending: This sub-component will synchronize the exact coordinates of each construction element described in the 3D model, created in the design phase.
4.8.3.5 Interfaces
4.8.3.5.1 Provides 3D Model
Table 40: Provides3DModel Interface
Information of a Service Description Provides 3D model Request Request URL GET api/service/:id Name Description UserID Name of the User ID Resource Required string Example: Building123 Parameters ModelID Model Identificate Required string Example: 1234 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes id The ID of the service Required integer Example: 21842 name The name of the service Required string Example: VoiceAssistant
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 164 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png Object Renderable 3D model Required object Example: Building1234.fbx
published Whether the service has already been published or not Required boolean Example: true
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.8.3.5.2 Get Project Documents and Details
Table 41: GetDocument&Details Interface
Information of a Service Description Get Project Documents and Details Request Request URL GET api/service/:id Name Description UserID Name of the User ID Resource Required string Example: Building123 Parameters DocumentID Document Identificate Required string Example: Window123 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes id The ID of the service Required integer Example: 21842 name The name of the service Required string Example: VoiceAssistant version The version of the service Required string Example: 1.0
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 165 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png Document Document requested Required object Example: Window123 Format Document Format [pdf|doc|dxf] Required format Example: Window123.dxf
published Whether the service has already been published or not Required boolean Example: true
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
4.8.3.6 Consumed Services Construction Profile uses services from Knowledge Information Storage to obtain documents and to create new information. The services that it uses are shown in the next table. Table 42: Consumed Services by Construction Profile
Consumed service by the Construction Profile
Service Section Reference
Create Object 4.10.5.1.6
Read Object 4.10.5.1.7
Update Object 4.10.5.1.8
Delete Object 4.10.5.1.9
4.8.4 Quality Profile
4.8.4.1 Overview The goals and structure of the Quality Profile have already been discussed in the above section ‘Information Data Model’. This section will only list the interface and the consumed services for this module.
4.8.4.2 Interfaces
4.8.4.2.1 Retrieve a Checklist Template
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 166 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 43: RetrieveChecklist Interface Information of an Service Description Retrieves a checklist template Request Request URL GET /accept/nexus/quality/checklists/:checklistTemplateId Name Description Resource Parameters checklistTemplateId Id of the checklist template Required integer Example: 42 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Attributes Name Description userId The ID of the user Required integer Example: 42 version The version number of the checklist template Required string Example: "3.2" taskId The ID of the task optional integer Example: 42 xml document the set of answers for the given checklist required string Example: -
4.8.4.2.2 Search Checklist Template Table 44: SearchChecklist Interface Information of an Service Description Search checklist templates matching some parameters Request Request URL GET /accept/nexus/quality/checklists/search JSON Name Description Attributes userId The ID of the user optional integer Example: 42 name The name of the checklist optional string Example: Insulation control
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 167 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
taskId The ID of the task optional integer Example: 42 buildingComponentId The ID of the building component optional integer Example: 42 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found
Example: answer [ a list of structure { templateId:'23', userId:'42', version:'1',
defined with the taskId:'242', xmlDoc:'xxxxx' }, following attributes { templateId:'26', userId:'49', version:'1', taskId:'243', xmlDoc:'yyyy' } ]
4.8.4.2.3 Post a new Checklist Answer Table 45: PostChecklist Interface Information of an Service Description Post a new checklist answer Request Request URL POST /accept/nexus/quality/checklists/answers
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 168 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
JSON Name Description Attributes checklistTemplateId The ID of the checklist template Required integer Example: 42 userId The ID of the user Required integer Example: 42 datetime The date and time when the answer was redacted Required date&time Example: 31/12/2015-23:59:59 taskId The ID of the task optional integer Example: 42 buildingComponentId The ID of the building component optional integer Example: 42 xml document the set of answers for the given checklist required string Example: -
Response
Value Description 200 OK HTTP Status Code 400 Invalid parameters
404 Service not found
4.8.4.2.4 Retrieve a Checklist Answer Table 46: RetrieveChecklist Interface Information of an Service Description Retrieve a checklist answer Request Request URL GET /accept/nexus/quality/checklists/answers/:checklistAnswerId Name Description Resource Parameters checklistTemplateId Id of the checklist answer Required integer Example: 42 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 169 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
JSON Attributes Name Description userId The ID of the user Required integer Example: 42 datetime The date and time when the answer was redacted Required string Example: 31/12/2015-23:59:59 taskId The ID of the task optional integer Example: 42 buildingComponentId The ID of the building component optional integer Example: 42 xml document the set of answers for the given checklist required string Example: -
4.8.4.2.5 Retrieve a Specific Metric Table 47: RetrieveSpecificMetric Interface Information of an Service Description Retrieves a specific metric Request Request URL GET /accept/nexus/quality/metrics/:metricId Name Description Resource Parameters metricId Id of the requested metric Required string Example: asPlannedInsulationAdequacy JSON Attributes Name Description groupBy the grouping criterion for the result set optional string Example: byMaterialType The start date-time for filtering the data the metric is startDateTime based on optional date-time Example: 2015-11-01:8.00 The end date-time for filtering the data the metric is endDateTime based on optional date-time Example: 42 The component type for filtering the data the metric componentType is based on optional date-time Example: 42 Response HTTP Status Value Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 170 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Code 200 OK 400 Invalid parameters 404 Service not found JSON Attributes Name Description metric an xml document describing the relevant metric xml document Example: -
4.8.4.3 Consumed Services The Quality Profile uses services from other profiles in the Profile Nexus to aggregate and analyse the quality of the building process: the Construction Profile, the User Profile, and the Project Workflow Profile. It also uses services from KIS to store checklists and sensor data streams. The services that it uses are linked in the following tables. Table 48: Consumed Services from KIS
KIS
Create Bucket KIS/Interface/4.10.5.1.2
List Buckets KIS/Interface/4.10.5.1.4
Describe Buckets KIS/Interface/4.10.5.1.3
Delete Bucket KIS/Interface/4.10.5.1.5
Create Object KIS/Interface/4.10.5.1.6
Read Object KIS/Interface/4.10.5.1.7
Update Object KIS/Interface/4.10.5.1.8
Delete Object KIS/Interface/4.10.5.1.9
Execute Generic Query KIS/Interface/4.10.5.1.10
Execute Delete Query KIS/Interface/4.10.5.1.11
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 171 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 49: Consumed Services from PN
Profile Nexus
Construction Profile
Get building component 4.8.2.5.2
Get material 4.8.2.5.2
User Profile
Get user 4.8.5.3
Workflow Profile
Get crew 4.8.6.1
Register to task event 4.8.6.3
Get task 4.8.6.3
Get task workflow 4.8.6.6
Get task path 4.8.6.3
Get tasks for material mismatch 4.8.6.4
Get tasks for component mismatch 4.8.6.4
Get tasks for duration mismatch 4.8.6.4
4.8.5 User Profile
4.8.5.1 Overview The goals and structure of the User Profile have already been discussed in the above section ‘Information Data Model’. This section will only list the interfaces of this module. Data flows in and out of the User Profile component happens in two distinctive ways. The incoming updates are event driven and read only data can be consumed via a set of REST interfaces.
4.8.5.2 Updating User Profile Data To provide real-time event-driven updates the User Profile component makes use of the AMF (Autonomous Messaging Framework). The component is connected to the communication bus and listens for incoming massages that can be sent by other components to it as the recipient for an explanation how this can be done). These messages add or update existing used data in the User Profile. The format of these messages is following:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 172 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Listing 4: Format of an Update User Message
4.8.5.3 Retrieving User Profile Data Retrieving read-only user profile data is done using the REST interfaces described below.
4.8.5.3.1 Interface Find Users The REST interface “findUsers” (Table 50) allows searching for users applying complex search criteria. Table 50: Find Users Interface Information of a Service Description Returns a list of users that fulfil search criteria Request Request URL GET /accept/nexus/users/findUsers:searchFilter Name Description Resource Parameters searchFilter JSON structure describing a filter. Optional object Example:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 173 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ “skills”: [ “bricklayer” ], “accessRights”: [ “building1” ] } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Attributes Name Description Template JSON object with the answer. JSON object Example: { “userId”: 1, “userName”: “John Smith”, “roles”: [“Construction worker”], “skills”: [“bricklayer”, “crane operator” ], “accessRights”: [“building1”, “basement2” ], “calendarUrl”: “https://calendar.google.com/calendar/hosted/...” }
4.8.5.3.2 Interface Access Rights The REST interface “accessRights” (Table 51) allows listing all users that have a particular access right. Table 51: List Users with an Access Right Interface Information of a Service Description Returns a list of users that have a particular access right Request Request URL GET /accept/nexus/users/accessRights/:accessRight Name Description Resource accessRight Return all users that have this access right. Parameters Required string Example: building1
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 174 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Attributes Name Description Template JSON object with the answer. JSON object Example: { “userId”: 1, “userName”: “John Smith”, “roles”: [“Construction worker”], “skills”: [“bricklayer”, “crane operator” ], “accessRights”: [“building1”, “basement2” ], ““calendarUrl”: “https://calendar.google.com/calendar/hosted/...” }
4.8.5.3.3 Interface Skills The REST interface “skills” (Table 52) allows listing all users that have a particular skill. Table 52: List Users with a Skill Interface Information of a Service Description Returns a list of users that have a particular skill Request Request URL GET /accept/nexus/users/skills/:skill Name Description Resource skill Return all users that have this skill. Parameters Required string Example: bricklayer Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 175 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
JSON Attributes Name Description Template JSON object with the answer. JSON object Example: { “userId”: 1, “userName”: “John Smith”, “roles”: [“Construction worker”], “skills”: [“bricklayer”, “crane operator” ], “accessRights”: [“building1”, “basement2” ], “calendarUrl”: “https://calendar.google.com/calendar/hosted/...” }
4.8.5.3.4 Interface Roles The REST interface “roles” (Table 53) allows listing all users that have a particular role. Table 53: List Users with a Role Interface Information of a Service Description Returns a list of users that have a particular role Request Request URL GET /accept/nexus/users/roles/:role Name Description Resource role Return all users that have this skill. Parameters Required string Example: Construction worker Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Attributes Name Description Template JSON object with the answer. JSON object Example: { “userId”: 1,
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 176 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“userName”: “John Smith”, “roles”: [“Construction worker”], “skills”: [“bricklayer”, “crane operator” ], “accessRights”: [“building1”, “basement2” ], “calendarUrl”: “https://calendar.google.com/calendar/hosted/...” }
4.8.5.4 Summary This section described how one can update and read User Profile data within the Profile Nexus. The User Profile component uses event-driven updates via the AMF and its data can be retrieved via a set of REST interfaces.
4.8.6 Workflow Profile The goals and structure of the Project Workflow Profile have already been discussed in the above section ‘Information Data Model’. This section will only list the interfaces of this module. Project Workflow Profile is designed to: Provide all relevant information related to tasks and subtasks Support an efficient coordination of construction works by providing list of tasks and by actualizing current status of tasks and providing alert/notification about any problems occurred during the task Provide workflow for scheduled tasks and/or subtasks on construction site in order to support installation process of building components and materials according to the rules of the trade Assign crews to a specific task and to a specific location (where task has to be performed) Synchronize supply side with construction process in terms of just-in-time deliveries. The component exposes the following REST interfaces:
4.8.6.1 Interface Get Crew The REST interface “getCrew” (Table 54) allows retrieving a crew by its id. Table 54: Get Crew Interface Information of a Service Description Returns a crew by it identifier Request Request URL GET /accept/nexus/workflow/getCrew/:id Resource Name Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 177 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Parameters id Unique id of the crew. Required integer Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Crew not found JSON Attributes Name Description JSON object JSON object with the response. Example: { “id”: 1, “name”: “Crew 1”, “start_date”: 1362196405309 “end_time”: 1462196405309 “total_working_hours”: 100, “presence_list”: [ { “userId”: 1, “worker_acronym”: “foreman1” “worker_name”: “John”, “foreman”: true } ] }
4.8.6.2 Interface Update Crew The REST interface “updateCrew” (Table 55) allows updating or adding a particular crew. Table 55: Update Crew Interface Information of an Service Description Updates or adds a particular crew Request Request URL POST /accept/nexus/workflow/updateCrew:crewInfo
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 178 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Name Description crewInfo JSON structure representing a crew. Required object Example: { “id”: 1, “name”: “Crew 1”, “start_date”: 1362196405309 “end_time”: 1462196405309 Resource “total_working_hours”: 100, Parameters “presence_list”: [ { “userId”: 1, “worker_acronym”: “foreman1” “worker_name”: “John”, “foreman”: true } ] } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Crew not found JSON Attributes Name Description id Id of the crew (added or updated) Required integer
4.8.6.3 Interface Get Task The REST interface “getTask” (Table 56) allows retrieving a task or a subtask by its id. Table 56: Get Task Interface Information of a Service Description Returns a task or a subtask by it identifier
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 179 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Request Request URL GET /accept/nexus/workflow/getTask/:id Name Description Resource Parameters id Unique id of the task. Required integer Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Task not found JSON Attributes Name Description JSON object JSON object with the response. Example: { “id”: 1, “task_list_id”: 1, “construction_area_id”: 1, “quantity”: 5, “unit_of_measure”: “m3”, “work_hours”: 100, “start_date”: 1362196405309, “end_date”: 1462196405309, “dependency_relationship”: “S-S”, “dependency_type”: “Hard”, “description”: “Building foundation”, “company”: “builder1”, “task_cost”: 10000, “priority”: “M”, “subtaskIds”: [ 1, 3, 10 ], “temperature_dependency”: { “type”: “above”, “temperature”: 0
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 180 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
} }
4.8.6.4 Interface findMismatchedTasks The REST interface “findMismatchedTasks” (Table 57) can be used to find all material, component or duration mismatched tasks. Mismatched tasks are identified based on workflow and control point checklists analysis. Table 57: Find Mismatched Tasks Interface Information of a Service Description Returns a list of mismatched tasks Request GET /accept/nexus/workflow/getMismatchedTasks/:taskListId Request URL /material|component|duration Name Description Resource Parameters taskListId Unique id of the task list. Required integer Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Task list not found JSON Attributes Name Description JSON object JSON object with the response. Example: { “task_ids”: [1, 3, 10] }
4.8.6.5 Interface Update Task The REST interface “updateTask” (Table 58Table 50Table 50: Find Users Interface) allows updating or adding a particular task or a subtask. Table 58: Update Task Interface Information of a Service Description Updates or adds a particular task or a subtask
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 181 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Request Request URL POST /accept/nexus/workflow/updateTask:taskInfo Name Description taskInfo JSON structure representing a task. Required object Example: { “id”: 1, “task_list_id”: 1, “construction_area_id”: 1, “quantity”: 5, “unit_of_measure”: “m3”, “work_hours”: 100, “start_date”: 1362196405309, Resource “end_date”: 1462196405309, Parameters “dependency_relationship”: “S-S”, “dependency_type”: “Hard”, “description”: “Building foundation”, “company”: “builder1”, “task_cost”: 10000, “priority”: “M”, “subtaskIds”: [ 1, 3, 10 ] ], “temperature_dependency”: { “type”: “above”, “temperature”: 0 } } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Task not found JSON Attributes Name Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 182 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
id Id of the task or subtask (added or updated) Required integer
4.8.6.6 Interface Get Task Workflow The REST interface “getTaskWorkflow” (Table 59) can be used to retrieve a task or a subtask workflow by its id. Table 59: Get Task Workflow Interface Information of a Service Description Returns a task or a subtask workflow by its identifier Request Request URL GET /accept/nexus/workflow/getTaskWorkflow/:id Name Description Resource Parameters id Unique id of the task workflow. Required integer Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Task workflow not found JSON Attributes Name Description JSON object JSON object with the response. Example: { “id”: 1, “task_id”: 3, “name”: “example workflow”, “date”: 1362196405309, “notes”: “Workflow notes”, “creator_user_id”: 3, “workflow_steps”: { “workflow_step”: { “control”: { “id”: 1,
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 183 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“date”: 1362196405309, “name”: “DC1”, “type”: “DC”, “status”: “success”, “alert”: true, “alert_description”: “DC1 done” } }, “workflow_step”: { “activity”: { “id”: 1, “start_date”: 1362196405309, “end_date”: 1462196405309, “name”: “Activity1”, “number_of_days”: “5”, “status”: “success”, “alert”: true, “alert_description”: “Activity1 done” }, “control”: { “id”: 2, “date”: 1362196405309, “name”: “AC1”, “type”: “AC”, “status”: “success”, “alert”: true, “alert_description”: “AC1 done” } } } }
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 184 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.8.6.7 Interface Update Task Workflow The REST interface “updateTaskWorkflow” (Table 60) allows updating or adding a particular task or a subtask workflow. Table 60: Update Task Workflow Interface Information of a Service Description Updates or adds a particular task or a subtask workflow Request Request URL POST /accept/nexus/workflow/updateTaskWorkflow:taskWorkflowInfo Name Description taskInfo JSON structure representing a task workflow. Required object Example: { “id”: 1, “task_id”: 3, “name”: “example workflow”, “date”: 1362196405309, “notes”: “Workflow notes”, “creator_user_id”: 3, “workflow_steps”: { “workflow_step”: { Resource “control”: { Parameters “id”: 1, “date”: 1362196405309, “name”: “DC1”, “type”: “DC”, “status”: “success”, “alert”: true, “alert_description”: “DC1 done” } }, “workflow_step”: { “activity”: { “id”: 1,
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 185 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“start_date”: 1362196405309, “end_date”: 1462196405309, “name”: “Activity1”, “number_of_days”: “5”, “status”: “success”, “alert”: true, “alert_description”: “Activity1 done” }, “control”: { “id”: 2, “date”: 1362196405309, “name”: “AC1”, “type”: “AC”, “status”: “success”, “alert”: true, “alert_description”: “AC1 done” } } } } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Task not found JSON Attributes Name Description id Id of the task or subtask workflow (added or Required integer updated)
4.8.6.8 Interface Subscribe to Workflow Notifications The REST interface “subscribeWorkflowNotifications” (Table 61) allows a component to subscribe or unsubscribe for receiving notifications via AMF if changes in the workflow occur (e.g., workflow is created, an alert is generated, etc.). The Project Workflow Profile
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 186 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
will send a message to the component specified in subscription each time a change in the workflow of the requested task occurs. Table 61: Subscribe to Workflow Notifications Interface Information of a Service Descriptio Lets a component subscribe to notifications about workflow changes (e.g. n workflow creation) Request
Request POST URL /accept/nexus/workflow/subscribeWorkflowNotifications:subscriptionInfo Name Description subscriptionInfo JSON structure representing a task workflow Required object notification subscription. Example: { Resource Parameter “task_id”: 1, s “participant_user_id”: 3, “component”: “KIS”, “service”: “notifyUser”, “subscribe”: true } Response Value Description HTTP 200 OK Status Code 400 Invalid parameters 404 Task not found JSON Attributes Name Description
4.8.6.9 Interface Subscribe to Workflow Control Reminders The REST interface “subscribeWorkflowControlReminders” (Table 62) allows a component to subscribe or unsubscribe for receiving reminders via AMF for doing checklists at control points (e.g., do a Delivery Checklist). The Project Workflow Profile will send a message to the component specified in subscription each time a checklist needs to be filled. Table 62: Subscribe to Workflow Control Reminders Information of a Service
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 187 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Lets a component subscribe to control reminders (e.g., “do a Delivery Description Checklist”) Request POST Request /accept/nexus/workflow/subscribeWorkflowControlReminders:subscriptionIn URL fo Name Description subscriptionInfo JSON structure representing a control reminder Required object subscription. Example: { Resource “control_id”: 1, Parameters “participant_user_id”: 3, “component”: “KIS”, “service”: “remindUser”, “subscribe”: true } Response Value Description HTTP 200 OK Status Code 400 Invalid parameters 404 Task not found JSON Attributes Name Description
4.8.6.10 Interface Attach Report The REST interface “attachReport” (Table 63) allows uploading a completed checklist for a workflow step (activity or control). Upon uploading of the report the system will re-evaluate the workflow and send out necessary alerts to subscribed users Table 63: Attach Report Information of a Service Description Attaches a completed checklist to a workflow step (activity or control) Request Request URL PUT /accept/nexus/workflow/attachReport:reportInfo Resource Name Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 188 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Parameters reportInfo JSON structure representing a report. Required object Example: { “control_id”: 1, “submitting_user_id”: 3, “component_report”: { }, “material_report”: { } } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Task workflow step not found JSON Attributes Name Description id Required integer Id of the report
4.8.6.11 Summary This section described how one can update and read Project Workflow Profile data within the Profile Nexus. The Project Workflow Profile component can send asynchronous reminders and notifications via AMF and its can be controlled via a set of REST interfaces. 4.9 Service Market Place
4.9.1 Overview The service market place is the main resource for end users that want to extend their ACCEPT experience with additional functionalities and features. These extensions are called services and are available for every ACCEPT user that has the marketplace app installed. A service consists of one specific feature and is not a standalone app for itself. They can be developed by the official ACCEPT team or any other third party. There are four user groups within the market place: Admin: Admins can remove, add and edit existing services for in case that there are any problems.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 189 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Developer: Developers create services for the ACCEPT system. They will be responsible of the publication and management of their own services. Reviewer: Once a developer submits his service, that service is first being reviewed by three reviewers before accepting and adding it into the market place to ensure more security for the end user. The reviewers can accept or reject a submission. End user: End users will download, install and remove apps using their market place app. They will also be able to rate and comment on existing services based on their experience.
4.9.2 Major Design Decision Ease of use: The service market place should be easy to use, because end users are not supposed to be technology experts. The only exception to this is the interface for the reviewer group, because they need to have knowledge of the system to some degree. Size: The maximum size of a service within the market place is 100MB. Big files like 3D models are supposed to be stored and accessed using the profile nexus.
4.9.3 Technology Comparison The market place itself will be a restful API which provides information for the clients to access the market place. That REST API could be implemented in almost any language, though there are some with features specifically made for that purpose. The webserver behind the market place has to be concurrent to support multiple requests at the same time, and therefore the language of choice should have that in focus. Fitting languages: Rust: Although this language would be perfect for this task, because it is focused on concurrency and safety it is still in a too early stage of development to use it in production. Go: The Go programming language is designed with concurrency and ease of use in mind abstracting the low level nature of native code, though it is not mature enough yet to be used in production. Node: Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient. It provides a lot of different frameworks aimed at exactly those kind of functionality that we need to provide. It’s stable enough to be used in production and has a lot of tooling to support an efficient development of the REST API. As specific parameter is used: Framework support. A broad range of frameworks can speed up the development of the component by a great amount. The more frameworks there are, the higher the chance that we don’t have to reinvent the wheel for that specific part. Concurrency. The REST API for the service market place has to handle a lot of connections at the same time, therefore the technology to use should be concurrent by default. Language security / abstraction layer. The service will be open from the web, therefore it is an easy target for intruders. This can be solved by adding a strong
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 190 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
security layer by for example using a virtual machine to run the server to separate the instance from the underlying operating system. Table 64: SMP Technologies comparison
Parameter Importance Rust (Rustless) Go(go-restful) NodeJS
Generic Parameters
Maturity & Stability +++ + + +++
State of the art +++ ++ ++ +++
Open Source & standards +/- YES YES YES
Extensibility +++ +++ +++ +++
Performance / Scalability +++ ++ ++ +++
Familiarity & Support & + + + +++ Community
EU Project Origin + +/- +/- +/-
Licenses +/- MIT MIT MIT
Specific Parameters
Framework support +++ ++ + +++
Concurrency +++ + ++ +++
Language security / abstraction +++ ++ + +++ layer
4.9.3.1 Technology Selection Based on its concurrent nature and its broad framework support for REST APIs node.js is the perfect fit for this task. The interpreter itself is fast enough to support backend software and provides high security standards by abstracting the low level layer of the operating system. The REST API framework loopback which is built on top of the express framework supports dynamic end-to-end REST APIs, external data sources and much more which speeds up the development by a great amount. The loopback framework will be used as the base to implement the service. The storage of the data will be handled by the KIS which will be connected to the market place service using the BUS.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 191 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.9.4 Component Structure This component contains two separate marketplaces that are separated by their target users. The developer and reviewer user group have a different frontend than the end users.
Figure 39: UML Component Diagram – Market Place Service
4.9.4.1 Service Interaction The first part of the bundle is the interaction tier, which is used by the frontend to communicate with the market place and the ACCEPT system. No other component of the
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 192 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
service is accessible from the outside. The only task for the Interaction layer is to forward the requests to the Service logic layer and send the responses back. Therefore, if there are any changes to the general logic of the component, the Interaction layer does not have to be changed. Similarly, a change in the Interaction layer does not require the change of several components in the Service functionality.
4.9.4.2 Service Logic The second layer, the logic layer, handles the entire decision making, the computations and contains the general functionality of the service. It consists of multiple components, which handle different tasks: The Service Controller provides the interaction between the interaction layer and logic layer of the service. It handles the coordination of the service logic and communicates to other ACCEPT modules. The Service Deployment Manager handles everything deployment related for the services (extensions) of the market place. These include things like installation, removal, registration and editing of extensions to the service. The Service Registry aggregates and stores all the service related data. The Profile Manager handles the different user groups, and their associated rights. The Access Manager is in charge of handling everything concerning the authorisation and authentication within the service. It will be used to check if a specific user is authorised to do certain actions in the service. For example, it ensures that a user can only view and download a new service instead of adding one.
4.9.4.3 Data The Data layer of the Service provides an interface to the Security functions like Authorisation and Authentication. Furthermore, the ACCEPT Model is responsible for accessing other ACCEPT components like the Profile Nexus, the Knowledge Information Storage and provide the authentication to those components.
4.9.5 Interfaces This section describes the RESTful interface provided by the Service Manager subcomponent. This interface will be used by the SiMa and the CoOpApp to implement the ui for the different platforms. The parameters to the methods and the return values are json formatted strings. To shorten the following tables and to follow the REST standards the base url is not being mentioned in the request url. The base url is the following: http://accept- project.com/marketplace/
4.9.5.1 Information of a Service The following REST method provides detailed information of a service. The method accepts the id of the service as a parameter and returns the service object.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 193 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Table 65: RESTful Interface Description – Information of a Service
Information of an Service Description Provides information of the last version of a published service Request Request URL GET api/service/:id Name Description Resource Parameters id Id of the app Required integer Example: 21842 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes id The ID of the service Required integer Example: 21842 name The name of the service Required string Example: VoiceAssistant version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png rating The user rating of the service (from 0-5) Required string Example: 4.9
published Whether the service has already been published or not Required boolean Example: true
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
The following listing is an example of the JSON call:
{ "id" : 21842 } Listing 5: Service Information
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 194 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The JSON response will contain the detailed information of a service.
{ "id": 21842, "name": "VoiceAssistant", "version": "1.0", "date": "23/05/2015", "iconUrl": "/assets/icon.png", "rating": "4.9", "published": true, "author": "John ", "supportContact": " [email protected] " }
Listing 6: App Information
4.9.5.2 Information of a Service by version The following REST method provides detailed information of a service filtered by the version. The method accepts the id and the version of the service as a parameter and returns the service object. Table 66: RESTful Interface Description – Information of a Service by Version
Information of an Service by Version Description Provides information of the last version of a published service Request Request URL GET api/service/:id/:versionNumber Resource Name Description Parameters id Id of the app Required integer Example: 21842
versionNumber Version of the app Required integer Example: 1.0 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes serviceId The ID of the service Required integer Example: 21842 name The name of the service Required string Example: VoiceAssistant
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 195 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png rating The user rating of the service (from 0-5) Required string Example: 4.9
published Whether the service has already been published or not Required boolean Example: true
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
The following listing is an example of the JSON call:
{ "id" : 21842, "version": "1.0" } Listing 7: Service Information
The JSON response will contain the detailed information of an app.
{ "id": 21842, "name": "VoiceAssistant", "version": "1.0", "date": "23/05/2015", "iconUrl": "/assets/icon.png", "rating": "4.9", "published": true, "author": "John", "supportContact": " [email protected] " } Listing 8: Service Information
4.9.5.3 List Of All Services Table 67: RESTful Interface Description – List of all Services
Get List of all Services Description Provides the list of all available services Request D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 196 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Request URL GET api/services/ Name Description sorting Sorting parameter Optional string Example: version Resource Parameters offset Start of the pagination Optional integer Example: 5 limit Number of elements in response Optional integer Example: 50 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes id The ID of the service Required integer Example: 21842 name The name of the service Required string Example: VoiceAssistant version The version of the service Required string Example: 1.0 date The date of publication Required string Example: 23/05/2015 iconUrl The url of the icon of the service Required string Example: /assets/icon.png rating The user rating of the service (from 0-5) Required string Example: 4.9
published Whether the service has already been published or not Required boolean Example: true
author The name of the author Required string Example: John supportContact The support contact of the service Required string Example: [email protected]
The following listing is an example of the JSON call:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 197 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ "sorting": "version", "offset": 0, "limit": 50 } Listing 9: List of Services
The JSON response will contain a list with detailed information of all services.
{ "services": [ { "id": 21842, "name": "VoiceAssistant", "version": "1.0", "date": "23/05/2015", "iconUrl": "/assets/icon.png", "rating": "4.9", "published": true, "author": "John", "supportContact": " [email protected] " } ] } Listing 10: List of Services
4.9.5.4 Update Existing Service Table 68: RESTful Interface Description – Update a service
Update Information of a Service Description Updates an existing service instance or inserts new one Request Request URL PUT api/services/:id Name Description Resource Parameters service Object json representation Required service Example: {service: {…} } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 198 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Attributes id The ID of the service Required integer Example: 21842
The following listing is an example of the JSON call:
{ "id": 21842, "name": "VoiceAssistant", "version": "1.0", "date": "23/05/2015", "iconUrl": "/assets/icon.png", "rating": "4.9", "published": true, "author": "John", "supportContact": " [email protected] " } Listing 11: Update a service
4.9.5.5 Add New Service Table 69: RESTful Interface Description – Add a service
Insert new Service Description Inserts a new service Request Request URL POST api/services/:id Name Description Resource Parameters service Object json representation Required service Example: {service: {…} } Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found JSON Name Description Attributes id The ID of the service Required integer Example: 21842
The following listing is an example of the JSON call:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 199 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ "id": 21842, "name": "VoiceAssistant", "version": "1.0", "date": "23/05/2015", "iconUrl": "/assets/icon.png", "rating": "4.9", "published": true, "author": "John", "supportContact": " [email protected] " } Listing 12: Insert a service
4.9.5.6 Get Binary of a Service Table 70: RESTful Interface Description – Add a service
Binary of a service Description Provides the binary of a service Request Request URL GET api/binaries/:id/:version Name Description id Id of the service Resource Required integer Example: 21842 Parameters version Version of the service Required string Example: 1.0 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found
The following listing is an example of the JSON call:
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 200 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
{ "id": 21842, "version": "1.0" }
Listing 13: Insert a service
4.9.5.7 Rate a Service Table 71: RESTful Interface Description – Rate a service
Rate a service Description Rate a service Request Request URL POST api/ratings/:id/:version/:rating Name Description id Id of the service Required integer Example: 21842 Resource version Version of the service Parameters Required string Example: 1.0 rating The rating Required integer Example: 2 Response Value Description HTTP Status 200 OK Code 400 Invalid parameters 404 Service not found
The following listing is an example of the JSON call:
{ "id": 21842, "version": "1.0", "rating": 2 }
Listing 14: Insert a service
4.9.6 Consumed Services Knowledge and Information Storage o Create Bucket o Delete Bucket o CRUD-Operations o Search
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 201 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.9.7 Summary Several technologies that could serve as a base technologie for the ACCEPT Marketplace have been examined in regards of different requirements. Especially critical requirements like used langauge and framework, performance and security characteristics, extensibility and ease of use as well as more unciritical but also telling indictators of a suitable technology like the community support, the stability, the maturity and up-to-datedness have been examined and rated to make final technology decisions. The ACCEPT Marketplace will be based on the loopback framework to implement most of the CRUD operations for the REST interface automatically and use the KIS for the data storage via its REST interface.
4.10 Knowledge and Information Storage
4.10.1 Overview The Knowledge and Information Storage (KIS) is the central point for all data in the ACCEPT system. It aims to provide a generic data storage solution as an ACCEPT Service to the rest of the system. KIS abstracts different storage technologies to provide a unified storage service to other components. These services will be provided as web services to any legitimate user of the ACCEPT system. Since the ACCEPT system will handle and process sensitive data (such as worker profiles and sensor data) data privacy and security is a prominent technical concern. The KIS will provide complete separated storage areas as so called data buckets. Each data bucket can be utilised to create isolated isles of data. By using different buckets for each user, the confidential data of one user is stored completely separated from the data of another user.
4.10.2 Major Design Decisions The data of the ACCEPT system can be characterised by three crucial attributes. Firstly, the system provides data in great quantities. Secondly, the overall data of the ACCEPT system is diverse; it can be categorized as followed: Profile data – This includes profiles for users, sensors, workflows, quality, and construction projects. Such profile data is essential to ACCEPT’s value, it provides the primary content of various functionalities across the system. For example, a sensor profile might contain an ID for the sensor, a description of the sensor, and an archive of the sensor’s readings; a construction project profile might contain information about the location, schedule and deadlines of the profile. Viki data – This includes Execution Detail Assets (EDA) and Extended Virtual Annotations (EVA). These two assets constitute the basis of ACCEPT’s augmented reality capacities, the former consisting of larger assets that somehow illustrate or detail the execution of some construction process, and the latter consisting of user generated notations that can be “attached” to locations within AR and supplement the EDAs.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 202 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
SMP data – This data will be used to populate the Service Market Place (SMP), and consists of third and first party applications. It must be decided what form these applications will take on the KIS, but in any case they must be able to be downloaded and installed on the SiMaApp and CoOpApp. The third crucial attribute of the data in the ACCEPT system is its sensitivity due to its encompassing and detailed nature – the data will concern many different aspects of large, valuable projects. In order to meet the requirements, the solution has to be thereby scalable and adaptable, but also private. This will be fulfilled by storing the data in so called data buckets. The data of each data bucket can be distributed over different kinds (adaptable) of any number (scalable) of databases, while also being optionally encrypted (private). In addition, each data bucket will be an “aisle”, meaning it is isolated from the other buckets, which further enhances security. To allow third party developers as well as first party developers of the ACCEPT system the access to storage with simplicity, the data will be stored encapsulated as different data types. The KIS will offer simple CRUD (Create, Read, Update, Delete) operations for all of these data types e.g., returning values of a data set or updating properties of a data entry. Additionally, the KIS will provide more advanced query capabilities based on specific data types, as different data types have different requirements. For example, storing large amounts of binary data files requires optimal data throughput while a semi-structured data needs to be able to be retrieved via queries while data throughput is a secondary factor. Consequentially, several technologies will be utilized to support the different data types. Each end user of the ACCEPT system will have different data buckets to store the user specific data. Each of these data buckets has a different Sensitivity Level. This will allow a balance between data privacy and usability. Private data is only accessible for the owner of the data. The data can only be accessed by the third party applications if explicitly allowed. The data will be not available for the ACCEPT system. Protected data is accessible by the ACCEPT system to work properly. The data can be made explicitly available for third party applications. Internal data is accessible by the ACCEPT system as well as any third party applications from the ACCEPT marketplace. The end user will have total control over his data by defining the sensitivity level of his data. The Sensitivity Level of the buckets will be implemented with Access Control List (ACL). This separation of data in different data buckets will ensure the privacy and security of the user data. Besides the user data, every actor of the ACCEPT system can create data buckets in order to store data and utilize the ACL to specify exactly which other users or user groups can access their bucket. One component may use several different buckets and may specify their access rights to share data with other components. Each component may create multiple buckets for storing data, which are fully separated and not influenced by activities of other buckets. In order to handle the different aforementioned data types in the best way, three different concepts to store data are foreseen, each of them will utilize a different technology: Semi-Structured will be used to store typical data in a document-oriented way without a fixed data schema. It is usually referred to as “NoSQL” (non Structured D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 203 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Query Language) storage and may be realized by technologies such as CouchDB , Apache Cassandra or MongoDB. A typical data entry in this storage will have an ID and a set of key-value entries, sometimes being hierarchical. Binary data will allow a file-centric storage for binary data. It may be used to, e.g., store videos, PDFs or any other type or binary data. Queries will be based on the file name or ID, e.g., by requesting the content of document “brochure.pdf”. Potential base technologies include Amazon S3 or (distributed) file systems.
4.10.3 Technology Comparison For the realisation of the KIS component, it is necessary to identify adequate storage technologies to store the different data types – binary and semi-structured. The assessment of these data storages will be carried-out independently in the following sections, but each one shares a basis for the criteria for the technical specification (see Table 72). Table 72: KIS - Shared Criteria for Technical Specification – Storage Technologies
Parameter Importance Description
Scalability ++ Since ACCEPT may need to manage a large amount of data that will grow continuously, it is necessary to select a technology that can be expanded easily.
CRUD Operation ++ CRUD stands for create, read, update and delete and forms the Support base operations of any Database Management System (DBMS). It should be supported by all base technologies.
Response Time ++ Speed of writing or reading data from the data storage varies per data storage system used. So it is a very important decision criterion for choosing the underlying software/technology for the data storage.
Open Format + The chosen data storage systems hast to be able to be used in Compatibility different environments and by different components. As such, an open data format has to be chosen to transfer the queries and data between the data storage and the ACCEPT components. An “open” file format is defined as one that is open source, and usually, standardized.
Costs for Data Storage ++ From an economic point of view, the costs for the data storage should be included in the selection decision, especially when considering cloud-based storages as some are fully managed and the usage of them is not for free.
Cloud Compatibility ++ Not all of the existing data storage systems are absolutely suitable to work within a cloud-based system. Therefore it is pivotal whether the chosen systems support it or not. Note: The selection in the following subsections is based on the different bucket types (binary and semi-structured). For managing those data types, a lot of proven technologies exist. For example, there are a lot of different approaches for storing structured information in relational databases. As such, the following selection will compare only the four to six most promising technologies for each area in order to keep the document sharp and short. D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 204 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.3.1 Backend-as-a-Service Backend-as-a-Service (BaaS) is a collection of technologies that are commonly required to handle application development (often on mobile platforms) integration with servers on the Internet. These commonly include persistent data storage and synchronization, user management, etc. The selected BaaS framework needs to be able to handle the delegation of user authorisation. Another consideration is the use of bulk operations, and how it will influence performance. The target platform must be able to combine operations where feasible, to minimize the overhead of individual network connections. CLIP is a storage mechanism developed by Ascora. It is built on top of MongoDB for raw data storage (which is scalable, highly available, and has good performance), and provides a containment wrapper to provide additional enhanced functionality. It supports the integration of external user authorisation components like users, groups, etc. It has clear specifications of the owner/context/scope for the data that is being operated on, allowing for a clear understanding of when data is personal and the permissions that are in effect on that data. It supports communication over a REST-based API, allowing data communication from essentially any Internet enabled device. Parse is a BaaS framework developed by a start-up company with the very same name. Its features a Cloud Based Service to store data. It comes with easy-to use client-APIs who provide the storage functionalities from within several platforms with focus on mobile app-development. It supports limited connection to external user management systems, but most of which are enterprise solutions, major web company logins (Google), or specifically defined formats like LDAP. It has a pay- per-use based pricing model, which presents the cost as a major consideration. BaasBox is an open-source BaaS similar to Parse. It is intended to provide a cloud- based storage solution for mobile app development. Internally the logic is coupled with OrientDB. Usergrid is an open-source BaaS. Developers can set up their own cloud-based data platform much faster than doing an implementation of their own. No server- side coding or back-end development is needed, as these features are realised by UserGrid. It uses Cassandra database and the logic is deployed on a Tomcat server or some other kind of webcontainer. Table 73: Technology Comparison of BaaS-systems
Parameter Importance CLIP Parse BaasBox UserGrid
Up-to-Datedness + ++ ++ + +
Stability +++ +++ +++ ++ -
Extensibility & Open + +++ - + + Source / Standards
Familiarity +++ +++ + + +
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 205 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Performance +++ +++ +++ ++ ++
Interoperability +++ +++ + + +
License + + - + +
Scalability +++ ++ + - +
Availability ++ + ++ + -
User Mgmt. +++ ++ ++ ++ ++ Integration
Costs for Usage and ++ + - + + Data Storage
Device Compatibility ++ + + + +
4.10.3.1.1 Technology Selection for Backend-as-Service CLIP is selected as BaaS for ACCEPT due to several reasons. It meets all demand of the project in terms of the criteria shown in Table 4 (TOTO Update reference). In particular, it can be adopted exactly to the needs when it comes to a custom authentication- and authorisation-system and extensibility. The open source solutions Usergrid and BaasBox might be changed according to the demands as well, but code integration is much more difficult as the internal structure of these projects is not known in contrast to CLIP. BaasBox lacks the possibility to scale, as the setup of several nodes is not supported by today. Apache UserGrid is still in development and the stable release version 1.0 is neither vastly documented nor will it be supported in the future, because development efforts tend toward version 2.0, which uses different technologies. Parse is a good and available commercial solution, which biggest drawback are the costs, who can be significant, if the number of web-requests exceed a certain limit. Furthermore, no custom authentication-system can be attached as the logic is not accessible to the ACCEPT developers.
4.10.3.2 Documentation Framework To allow for the rapid adaption by application users, a strong documentation corpus is needed. Modern documentation frameworks exist, that help collected API definitions, usage notes, code examples, and document templates into clean, interactive, and comprehensive document packages, that allow a developer to quickly locate the information about the API they are looking for, as well as sample code showing the API usage in the language the developer is using, so they can see the explanation and usage simultaneously with minimal effort. Slate is a tool for generating HTML pages from a defined mark-up input. Code samples can be specified in the input. Slate produces a single page HTML application as output, containing rich functionality such as search, selection of the client language being used, and the side-by-side display of the API documentation
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 206 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
and automatically syntax highlighted examples in the selected programming language. It has a modern look and feel with a responsive UI. An atomically generated index scrolls with the users progress, making it easy to identify the current location in the file. There is a strong community behind slate Swagger is a framework for generating API documentation. It uses a YAML format for its input. It contains browser based editor, allowing the rapid development and debugging of the API definitions. It creates HTML output, but uses an in-line content format that makes it difficult to view the textual description with the raw API specification. It also only focuses on REST APIs, and does not focus on specific client languages. Apimatic is a pay for service that can use description of REST APIs to generate client code for several different languages, without requiring that the backend developer have any understanding of the client-side programming languages. On online editor can be used to define the API, or alternatively an existing file definition could be imported. It also offers integration into continuous build systems. However, there is a monthly charge based upon KLOC. Table 74: Comparison of Documentation Frameworks
Parameter Importance Slate Swagger Apimatic
Up-to-Datedness + ++ +++ +++
Stability ++ +++ +++ +++
Extensibility & Open ++ +++ +++ ++ Source / Standards
Familiarity +++ +++ +++ ++
Performance + +++ +++ +++
Interoperability ++ +++ +++ ++
License + Apache 2.0 Apache 2.0 Proprietary
Cost +++ Free Free Per KLOC /month
Open Output (HTML) +++ +++ +++ +
Generated Code ++ ++ + ++ Sample Integration
Index/search +++ +++ + ++
Synchronous Display of ++ +++ ++ ++ Information
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 207 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.3.2.1 Technology Selection for Documentation Framework Slate was selected as the preferred API documentation framework. It is not only free, but produces a responsive single page web application, with a modern clean look, side-by- side documentation and code view, multiple programming language support, and enhanced functionality like in page searching.
4.10.3.3 Semi-Structured Data Storage Technologies Semi-Structured Data can be used to store data in a document-oriented way without a fixed data schema. It is often referred to as “NoSQL” (Not only Structured Query Language) storage. A typical data entry in this storage will have an ID and a set of key- value entries, sometimes being hierarchical. When it comes to Backend-as-a-Service, noSQL-databases are the databases of choice, as it can’t be anticipated in advance which structure the data to be stored will look like. The following databases can be utilized to store Semi-Structured Data: Amazon DynamoDB66 and SimpleDB67 are NoSQL database services. They are easy to use and have a very good scalability. In comparison to SimpleDB, DynamoDB is faster, more flexible and there are no restrictions to the capacity. For this reason, DynamoDB will be used for further comparisons. The core idea is based on distributed hash tables to ensure a high availability as well an incremental scalability. As an externally hosted solution, the use of DynamoDB will lead to additional cost. Microsoft Azure Table Storage Service68 is a NoSQL database service. It serves access over a RESTful interface or libraries for several programming languages such as .Net, Java and PHP. It allows having multiple values for an attribute; the attributes are differentiated by a timestamp, allowing the storage of temporal data. As an externally hosted solution, the use of the Azure Table Storage will lead to additional cost. MongoDB69 is schema-less open source database that is based on documents. The documents are represented internally with the help of the BSJON specification, which leads to a good performance. MongoDB is written in C++ and is available for Windows, Linux, OS X and Solaris. It serves libraries for many programming languages such as .Net, C++, Java, PHP. It contains a master-slave replication mechanism and can be run on Microsoft Azure or own hosted servers and is a cost- free solution. MongoDB is a good option for applications that require operation intelligence, flexibility in data management and applications that focus on content such as event logging, metadata management, inventory management, product catalogs and eCommerce applications. Key features of MongoDB include indexing, ad-hoc queries, replication, load balancing, auto-sharding, MapReduce jobs and high availability. Apache CouchDB70 is a document-based database that can be accessed by a RESTful interface. It is written in Erlang and has a plug-in-architecture, which allows
66 http://aws.amazon.com/de/dynamodb/ 67 http://aws.amazon.com/de/simpledb/ 68 http://www.windowsazure.com/en-us/ 69 http://www.mongodb.org/ 70 http://couchdb.apache.org/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 208 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
adding extensions. It contains a master-master merge replication mechanism. It can be hosted on own servers to avoid usage costs. CouchDB is a good option for applications that require aggregation of frequently changing data such as contacts, invoices, receipts, etc. Key features of CouchDB include on-the-fly document transformation, real-time change notifications, high availability, partition tolerance, eventual consistency, ACID semantics, MapReduce jobs, master set-ups and automatic conflict detection. Apache Cassandra71 is an open source, distributed database which can be considered as a hybrid of key-value and column oriented nature. Cassandra is a good option for applications that deal with mission critical data and require failure tolerance and high write throughput while not sacrificing read efficiency such as session storage, content management, profiles, preferences, etc. Cassandra run on top of large amount of commodity servers, offering high availability, low latency for operations and no single point of failure. The key features of Cassandra include linear-scale performance, ease of data storage and distribution, elastic scalability for read/write operations, fault tolerance and simplicity in its configurability. In Table 75, the comparison of the before listed technologies for the storage of the Semi-Structured Data is made. Table 75: KIS - Comparison of Technologies for Semi-Structured Data Storage
Parameter Importance Amazon Microsoft MongoDB Apache Apache DynamoDB Azure CouchDB Cassandra Table
Generic Criteria
Up-to-Datedness ++ +++ +++ +++ +++ +++
Stability + ++ ++ ++ ++ ++
Extensibility & + ++ ++ +++ ++ ++ Open Source / Standards
Familiarity - - - +++ ++ +++
Performance ++ +++ +++ +++ +++ +++
Interoperability ++ +++ +++ +++ ++ +
License Proprietary Proprietary GNU AGPL Apache 2.0 Apache 2.0 v3.0 (drivers: Apache2.0)
Specific Criteria
71 http://cassandra.apache.org/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 209 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Scalability ++ +++ +++ +++ +++ +++
CRUD Operation ++ +++ +++ +++ +++ +++ Support
Response Time ++ ++ ++ +++ +++ +++
Open Format + ++ ++ +++ +++ ++ Compatibility
Costs for Data ++ + + ++ ++ ++ Storage
Cloud ++ Yes Yes Yes Yes Yes Compatibility
4.10.3.3.1 Technology Selection for Semi-Structured Data Storage MongoDB was selected as semi-structured data storage, because it is very stable and has a good runtime performance. It is internally in use by at least one project partner that is involved in the development of the KIS. Thus, it is well-tested and the necessary knowhow is already available. MongoDB is an open source solution and uses the GNU Affero General Public License (AGPL), a non-infecting license. It is available for Windows, Linux, OS X and Solaris and drivers exist for many programming languages. The number of drivers continues to grow, because the community develops new ones for further programming languages. It can be run on its own server, in its own private cloud or on Microsoft Azure as a public cloud. The database supports replications by itself, so that the synchronization is fully integrated.
4.10.3.4 Binary Data Storage Technologies Binary data contains data stored in files such as documents, images or configuration files of applications. For that reason, a technology is needed which offers an easy to use and scalable storage. For storing binary data, the following technologies are compared: Amazon Simple Storage Service (S3)72 is a key-value storage which is accessible through web service interfaces like REST and SOAP. Amazon provides scalability, high availability and promises an availability of 99.99%. It is a fully managed and externally hosted service and so the usage would lead to additional cost for the project. GridFS is a storage for binary files included in MongoDB. Files to be stored are divided into chunks, which are stored in the databse as separate documents. Fuethermore, metadata can be attached to each file in the JSON-Format, which provides the possibility to add searchable information to the files. As GridFS is included in the MongoDB, the corresponding data can grow in size and reliability by adding sharding or replication to the databsebase setup. A File Server is a computer which provides a shared access to storage resources. It is attached to a network and accessed by attached workstations. It could be
72 http://aws.amazon.com/en/s3/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 210 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
installed in a dedicated or in a non-dedicated manner. In the first case, the dedicated server is specially configured as file server and does not offer any other functionality. In the second case, the server is used in parallel for other tasks. This can lead to worse performance. There are several ways and protocols to access the data of a file server regardless of the manner it is installed, e.g., FTP, SFTP, or HTTP. As a technology and not a product, this is free of charge and can be hosted externally or internally. In Table 76, the comparison of the before listed binary data storages is made. Table 76: KIS - Comparison of Technologies for Binary Data Storage
Parameter Importance Amazon S3 GridFS Simple File Server
Generic Criteria
Up-to-Datedness ++ +++ +++ +++
Stability + +++ +++ +++
Extensibility & Open + ++ +++ ++ Source / Standards
Familiarity - ++ ++ ++
Performance ++ +++ +++ +
Interoperability ++ +++ ++ ++
License Proprietary AGPL v3.0 Technology - specific
Specific Criteria
Scalability ++ +++ +++ +
CRUD Operation Support ++ +++ +++ +++
Response Time ++ ++ +++ ++
Open Format + ++ +++ +++ Compatibility
Costs for Data Storage ++ ++ +++ +
Cloud Compatibility ++ Yes Yes Technology - specific
4.10.3.4.1 Technology Selection for Binary Data Storage
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 211 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
GridFS73 was selected as a binary storage for files and other binary data. It can be hosted on self-managed servers. GridFS is implemented in order to become more flexible and independent from Amazon S3, which could be attached as an alternative secondary storage. Nevertheless integrating this service would add complexity and costs without a clear advantage. GridFS offers high availability and scalability. Furthermore, its fast interaction allows a coupling between binary and structured metadata which does not implicate requests to separate servers or databases.
4.10.4 Component Structure The diagram below shows the structure that has been updated to reflect the technology selection.
Figure 40 : KIS Component Structure Diagram To achieve its functionalities, KIS provides the following subcomponents as depicted in Figure 40: Client SDKs: This subcomponent provides the functionalities of the REST-API on a programming-language level. It provides access from within Java, C#, PHP, or JS
73 https://docs.mongodb.org/manual/core/gridfs/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 212 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
environment. As the signatures of those languages would not differ significantly, Java signatures are explained, but not for the other languages. REST-API: The REST-API is the interface between KIS and the remaining ACCEPT Components as well as the Client SDKs. It provides the access to all query- and CRUD-operations. Authentication: This subcomponent takes care of users’ / components’ authentication. Authorisation: This subcomponent ensures that the users / components only have access to data they are authorised for. Storage Nexus: The Storage Nexus decouples the CRUD74 operations from advanced queries. It projects the incoming requests to the corresponding resources in the backend and prepares the responses. Storage Access: This subcomponent provides an abstraction layer around concrete storage implementations. This allows ACCEPT to replace one storage unit with another one if necessary. Hence, the flexibility of the storage system is increased. MongoDB: This is the storage system offering a concrete storage facility for a certain storage type. Following database types and systems are supported: Semistructured (MongoDB) and Binary (GridFS).
4.10.5 Interfaces The major design decision for the ACCEPT project is to use APIs, which are provided for several programming languages, as a common communication base for the ACCEPT components. These APIs each communicate with the RESTful interface internally. As the interfaces for other programming languages look similar, only the documentation for the Java-Interfaces as a Client-API are provided additionally to the REST-Interfaces.
4.10.5.1 RESTful Interfaces In order to describe the RESTful interface, each provided service is described in a separate table. This table shows an example for the JSON parameter (if applicable), as well as an example for the return value (if applicable).
4.10.5.1.1 Common Return Codes Table 77: RESTful Interface Description – Common Return Codes Value Description 200 Success 201 Created successfully 204 Success (no further detail/content is provided) 304 No change (The client should keep/use its current/cached version. No payload is included for efficiency)
74 Create, Read, Update and Delete D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 213 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
400 The server was unable to parse the request 401 Authorisation credentials are required, but not provided. Try again after logging in 403 The current user is not authorised 404 Page not found (Given by server) Bucket not found Document not found 405 Method not supported (Given by server) 409 Specific details about the submitted request have been rejected by the server. Modifying the request could yet result in a successful operation 412 The supplied ETag value is no longer valid 415 Unsupported Media Type. (Check the Content-Type header) 423 Document has been locked. See the “Retry-After” for the expected expiration. 500 Internal Server Error 501 This current server instance does not support this command. (It is not implemented, has been disabled within this context, etc.) 502 Database (or other supporting resource) is not available 503 The server is overloaded. Try again later. (Given by Server)
4.10.5.1.2 Method “Create Bucket” The RESTful interface “Create Bucket” creates a new Bucket for the specified owner. A Bucket is unique in the context of the owner and type.
Table 78: RESTful Interface Description – Create Bucket
Create Bucket
Description Creates a new bucket
Request
Request URL POST /version/accept/kis/owner/type/core
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 214 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
owner Name of the owner OwnerName Example: johndoe
type Datatype of resource(s) BucketType Example: data
JSON Body bucket_name : Name of the bucket to be created Parameters BucketName Examples: products, user_icons
acl Create bucket with special ACL AclDef? Response Value Description 201 Bucket has been created HTTP Status Code 409 Bucket already exists
… See Table X for miscellaneous codes
Name Description of value HTTP Headers Location? URL to the just created bucket, if successful HTTP Body Contains either an Object, no payload or a Message
4.10.5.1.3 Method “Describe Bucket”
This method delivers information about the requested bucket.
Table 79: RESTful Interface Description – Describe Bucket
Describe Bucket
Description Returns information about the bucket
Request
Request URL GET /version/accept/kis/owner/type/core/bucket_name
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 215 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
type Datatype of resource(s) BucketType Example: data
Bucket_name Name of the bucket BucketName Example: customers Response Value Description 200 Success HTTP Status Code 404 Bucket not found
… See Table X for miscellaneous codes HTTP Body Contains a Bucket Description Object
4.10.5.1.4 Method “List Buckets” The RESTful Interface “List Buckets” provides a list of Bucket IDs for the given owner and type. Table 80: RESTful Interface Description – Delete Bucket
List Buckets
Description Retrieves a list of buckets for a type
Request
Request URL GET /version/accept/kis/owner/type/info
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype of resource(s) BucketType Example: data Response Value Description HTTP Status 200 Success Code … See Table X for miscellaneous codes HTTP Body Delivers general bucket information and an array of Bucket IDs D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 216 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.5.1.1 Method “Describe Bucket” The RESTful Interface “Describe Bucket” provides meta-data associated with the bucket, but not directly contained by the bucket. Table 81: RESTful Interface Description – Describe Bucket
Describe Bucket
Description Returns information about the bucket
Request
Request URL GET /version/accept/kis/owner/type/core/bucket_name
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype of resource(s) BucketType Example: data
Bucket_name Name of the bucket BucketName Example: customers Response Value Description 200 Success HTTP Status Code 404 Bucket not found
… See Table X for miscellaneous codes HTTP Body Contains a Bucket Description Object
4.10.5.1.5 Method “Delete Bucket” The RESTful Interface “Delete Bucket”, deletes the specific Bucket for the specified owner. This will also delete all data stored in the Bucket. Normally only for the owner of the Bucket. Table 82: RESTful Interface Description – Delete Bucket
Delete Bucket
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 217 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Description Delets a bucket
Request
Request URL DELETE /version/accept/kis/owner/type/core/bucket_name
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype of resource(s) BucketType Example: data
bucket_name Name of the bucket BucketName Example: customers Response Value Description 200 Bucket has been deleted HTTP Status Code 404 Bucket not found
… See Table X for miscellaneous codes
4.10.5.1.6 Method “Create Object” The RESTful interface “Create Object”, executes a create operation on an existing Bucket. This will store the data of the transferred data object. The storage details are based on the data type of the transferred data object. For Semi-Structured (document based) collections, an array containing one or more JSON objects is expected. For Binary collections, either a JSON array of binary data objects or a single binary stream is expected. See https://docs.mongodb.org/manual/reference/mongodb-extended- json/#binary for details on binary objects in JSON. The single binary stream is used to create a single binary object with default values and is provided for environments with limited control, such as within a Web Browser.
Example: The string “mydata” with UTF-8 encoding: {"rawdata": [{"$binary": "bXlkYXRh", "type": "\x02"}]}
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 218 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The response for a request with an array of objects may contain an array of Object Description Objects, which can provide status, location, and other information about the created objects. The order of the array corresponds to the input array.
Table 83: RESTful Interface Description – Create Object(s)
Create Object(s)
Description Creates one or more new objects in a specific bucket for a specific user
Request
Request POST /version/accept/kis/owner/type/core/bucket_name URL
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype of resource(s) BucketType Example: bin
Bucket_name Name of the bucket where the object shall be stored BuckertName Example: customers
JSON Body rawdata An array of 1..n objects Parameters JSONobject[]
acl Create object(s) with special ACL(s) AclDef? Response Value Description HTTP 201 Object(s) created Status Code 404 Bucket not found
… See Table X for miscellaneous codes
Name Description of value HTTP Headers Location? URL to the created object. For single object only HTTP Body Contains either an array mapping an Object Descriptions or Messages per object requested.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 219 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.5.1.7 Method “Read Object” The RESTful interface “Read Object”, executes a read operation on an existing Bucket. This will retrieve all data objects of a specific type matching the query object. The matching criteria are based on the data type.
Table 84: RESTful Interface Description – Read Object
Read Object
Description Reads an object by passing its id
Request
Request URL GET /version/accept/kis/owner/type/core/bucket_name/id
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype of resource(s) BucketType Example: bin
Bucket_name Name of the bucket where the object shall be stored BuckertName Example: customers
id Name of the bucket ObjectId Example: 1a2b3c Response Value Description 200 Success HTTP Status Code 404 Bucket or Object not found
… See Table X for miscellaneous codes HTTP Body Contains either a JSON or Binary Object , or a Message
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 220 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.5.1.8 Method “Update Object” The RESTful interface “Update Object” performs an update operation on an existing Object. Table 85: RESTful Interface Description – Update Object
Update Object
Description Updates an object in a specific bucket for a specific user
Request
Request URL PUT /version/accept/kis/owner/type/core/bucket_name/id
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype BucketType Example: bin
Bucket_name Name of the corresponding bucket BuckertName Example: photos
id Name of the bucket where the object shall be stored ObjectId Example: photo_325
JSON Body rawdata An array with 1 object Parameters JSONobject
acl Updates the ACL of the object AclDef? Response Value Description 200 Object updated HTTP Status Code 404 Object not found
… See Table X for miscellaneous codes HTTP Body Contains either an Object, no payload or a Message
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 221 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.5.1.9 Method “Delete Object” The RESTful interface “Delete Object” deletes an Object. Table 86: RESTful Interface Description – Delete Object
Delete Object
Description Deletes an object in a specific bucket for a specific user
Request
Request URL DELETE /version/accept/kis/owner/type/core/bucket_name/id
Resource Name Description Parameters version Version of the REST-API Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype BucketType Example: bin
bucket_name Name of the bucket containing the object BuckertName Example: photos
id Id of the object to be deleted ObjectId Example: photo_325 Response Value Description 200 Object deleted HTTP Status Code 404 Bucker or Object not found
… See Table X for miscellaneous codes
4.10.5.1.10 Method “Execute Generic Query” The RESTful Interface “Execute Generic Query” executes a generic query on an existing Bucket. Table 87: RESTful Interface Description – Query Read
Query Read
Descripti Retrieve a filtered result from CRI. A paging mechanism is used to prevent the on response from being too large
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 222 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Request
Request POST /version/accept/kis/owner/type/core/bucket_name URL
Resource Name Description Paramete version Version of the REST-API rs Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype BucketType Example: data
bucket_name Name of the corresponding bucket BuckertName Example: customers
JSON last_id The value given by the last page read, or Null for the first Body read request issued. JSON? Paramete Example: 12345 rs limit MongoDB query to execute. Default query is to match everything. int? Example: 10
query MongoDB query to execute. Default query is to match everything. JSONobject?
order_by Sorting order object?
find_one (Not for paging, this is a single read) boolean
Response Value Description HTTP Status 200 Success Code … See Table X for miscellaneous codes HTTP Body Name Description
last_id To be given on the next page read, or Null if there is no further content. JSON
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 223 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
num_read int Number of records returned
values ReadInfo[]
1st Query: { “last_id”: null, “limit”: 10, “query”: { “value”: {“$gt”: 10}}, “order_by”: { “value”: 1}, “find_one”: false } 1st Response { “num_read”: 10, “last_id”: “1234567890-123-12345”, “values”: [ {“value”: 12}, {“value”: 12}, {“value”: 13}, … {“value”: 15}, ] } 2nd Query { “last_id”: “01234567890-123-12345”, “limit”: 10, “query”: { “value”: {“$gt”: 10}}, “order_by”: { “value”: 1},
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 224 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
“find_one”: false } 2nd Response { “num_read”: 1, “last_id”: null, “values”: [ {“value”: 16}, ] }
4.10.5.1.11 Method “Execute Delete Query”
Perform a mass deletion of documents that match a query. Table 88: RESTful Interface Description – Query Delete
Query Delete
Descripti Retrieve a filtered result from CRI. A paging mechanism is used to prevent the on response from being too large
Request
Request POST /version/accept/kis/owner/type/core/bucket_name URL
Resource Name Description Paramete version Version of the REST-API rs Designator Example: 1.0
owner Name of the owner OwnerName Example: johndoe
type Datatype BucketType Example: data
bucket_name Name of the corresponding bucket BuckertName Example: customers
JSON find_one (Not for paging, this is a single read) Body boolean Paramete rs query MongoDB query to execute to select the datasets to be
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 225 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
JSONobject? deleted
Response Value Description HTTP Status 200 Success Code … See Table X for miscellaneous codes HTTP Body Name Description Number of records deleted num_deleted Example: 10 int
4.10.5.2 Java Interfaces The Java interfaces act as wrappers for the RESTful interfaces. They provide a special convenient way to access KIS for Java developers. Also, having control over the client wrappers makes upgrading the server-side API easier, if changes on the client side are needed. Another advantage of having control over the client wrapper librarieasdfasdfs is, that clients can have additional information about server instances of KIS, which makes it possible to send requests to a different instance URI in case one of the instances fails unexpectedly.
4.10.5.2.1 Library GSON GSON75 is an Apache Licensed library for JSON handling from Google. It provides utility functionalities for converting Java Objects to and from JSON objects. Listing 15 demonstrates a conversion of a Java-Object to a JSON-object:
Gson gson = new Gson(); MyObject myObject = ...; JsonElement element = gson.toJsonTree(myObject)
Listing 15: Example – Converting a Java-Object to a JSON-Object.
4.10.5.2.2 Method “Create Bucket” The method “Create Bucket” is used to create a new Bucket on the KIS. It has a user- defined ID, type, and owner as parameters for the Bucket. The ID must be unique in the context of the user and type. In Listing 16, the signature of the method for “createBucket” is shown as well as an example for the usage of this method.
75 https://github.com/google/gson D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 226 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Listing 16: API Method Signature for Creating a Bucket and the Usage of this Method
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @return the description of the created object. * @throws RestException */ public abstract BucketDescription createBucket(ClipUser owner, BucketType bucketType, Designator bucketName) throws RestException;
…
//Creates a semi-structured bucket with the id "myBucket" Designator bucketName = new Designator("myBucket"); BucketDescription desc = api.createBucket(api.currentUser, BucketType.Data, bucketName);
The example usage of the method at the bottom of Listing 16 will create a new Bucket with the ID string of the variable “bucketName”. If the API call is successful a bucket description object will be returned, otherwise an exception will be thrown. 4.10.5.2.3 Method “List Buckets”
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @return a list of bucket IDs that match owner and bucketType. * @throws RestException */ public abstract List
…
List
Listing 17: API Method Signature for Listing Buckets and the Usage of this Method This method bottom of Listing 17 returns a list of Designators representing bucket IDs for a given type and owner. If there is a problem, an exception is thrown.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 227 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.5.2.4 Method “Describe Bucket”
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @return the description of the bucket * @throws RestException */ public abstract BucketDescription describeBucket(ClipUser owner, BucketType bucketType, Designator bucketName) throws RestException;
…
Designator bucketName = new Designator("myBucket"); BucketDescription about = api.describeBucket(api.currentUser, BucketType.Data, bucketName); System.out.println(about.getName()+" "+about.getType()+" "+about.getOwner()); System.out.println("Contains " + about.getItemCount() + " items"); EffectivePermissions effective = about.getCurrentUserEffectivePermissions(); System.out.println("Can Create: "+effective.isCanCreateDocs()); System.out.println("Can Read: "+effective.isCanReadDocs()); System.out.println("Can Update: "+effective.isCanUpdateDocs()); System.out.println("Can Delete: "Can Delete: "+effective.isCanDeleteDocs());
Listing 18:API Method Signature for Describing a Bucket and the Usage of this Method The function described in Listing 18 returns a listing of information about the bucket. If there is an error during the operation, an exception is thrown.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 228 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.5.2.5 Method “Delete Bucket” For the deletion of Buckets, the API provides the method “deleteBucket”. The method uses the name, type, and owner as parameters for identifying the Bucket to be deleted. In Listing 19, the signature of the method “deleteBucket” is shown, as well as an example for the usage of this method. /** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @throws RestException */ public abstract void deleteBucket(ClipUser owner, BucketType bucketType, Designator bucketName) throws RestException;
…
//Deleted the bucket with the ID “myBucket” Designator bucketName = new Designator("myBucket"); api.deleteBucket(api.currentUser, BucketType.Data, bucketName);
Listing 19: API Method Signature for Deleting a Bucket and the Usage of the Method The example usage of the method at the bottom of Listing 19 deletes the semi-structured bucket with the provided ID “myBucket” for the current user. All data saved in the Bucket will be deleted along with the Bucket. If there is an error during the operation, an exception is thrown.
4.10.5.2.6 Method “Create Object” To create a new data object in a bucket, the API provides the method “createBucket”. As example for a data object for this and all following examples, which require a data object Listing 20 shows a factory method. This method creates an instance of a test class. The listing is described below for completeness and explanatory reasons.
//Creates an instance of MyTestClass. private MyObject getTestObject() { MyObject test = new MyObject(); test.setTestAttributeBoolean(true); test.setTestAttributeInt(INT_BEFORE); test.setTestAttributeString(STRING_BEFORE); return test; }
Listing 20: Factory Method to Create a Test Data Object The “createObject” method of the API has four parameters. The first three respectively identify the owner, type, and name of the bucket in which the data object shall be stored. The last parameter is a list of data object to be stored in the bucket. In Listing 20, the signature of the method for the CRUD-operation “createObjects” is shown, as well as an example for the usage of this method.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 229 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @param objects A list of objects to create * @return A list of either ClipMessage or CreateInfo, corresponding to the 'objects' parameter. * @throws RestException */ public abstract List
…
Designator bucketName = new Designator("myBucket"); JsonObject obj1 = gson.toJsonTree(getTestClass()).getAsJsonObject();
Collection defList = new LinkedList
defList.add(obj1);
List
Listing 21: Operation createObject and the Usage of this Method The example usage of the method at the bottom of Listing 21 will store the created test data object in the bucket for semi-structured data with the name “myBucket” for the current logged in user. If the API call is successful, a listing of objects (either CreateInfo or Message objects) that respectively matches the list of specified objects will be returned.
4.10.5.2.7 Method “Read Object” To retrieve an existing data object from the CRI, the API provides the method “readObject”. Listing 22 shows the factory method which is used to read a data object. The “readObject” method of the API has four parameters. The first three identify the bucket from which the data objects shall be retrieved. The last is the object id for the data object which have to be read. In Listing 22 the signature of the method for the CRUD-operation “readObject” is shown, as well as an example for the usage of this method.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 230 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @param objectId The ID of the object being accessed * @return the object read as a JsonObject. * @throws RestException */ public abstract JsonObject readObject(ClipUser owner, BucketType bucketType, Designator bucketName, ClipObjectId objectId) throws RestException;
…
//Creates test data to query for data objects in the cloud storage CreateInfo cinfo = (CreateInfo)list.get(0);
JsonObject testObj = api.readObject(api.currentUser, BucketType.Data, bucketName, cinfo.getId());
MyObject myObj = gson.fromJson(testObj, MyObject.class);
Listing 22: Operation readDataObject and the Usage of this Method The example usage of the method at the bottom of Listing 22 creates a query object, which is used for the API call. The result list of objects is cast to the expected type. If no matching objects are found in the specific bucket the result list is empty.
4.10.5.2.8 Method “Update Object” To update attributes of existing data object in the CRI, the API provides the method “updateObject”. As mentioned before, for this the factory method shown in Listing 23 will be used. This method creates an instance of the test class MyObject. The “updateObject” method of the API has five parameters. The first three identify the bucket in which the data objects shall be updated. The fourth is the query data object used to identify the concerned data object. The last parameter is the new value for the data object which has to be updated in the Cloud Storage component.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 231 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @param objectId The ID of the object being accessed * @param object The new value for the given document. * @throws RestException */ public abstract void updateObject(ClipUser owner, BucketType bucketType, Designator bucketName, ClipObjectId objectId, JsonObject object) throws RestException;
…
JsonObject obj = gson.toJsonTree(new MyTestClass()).getAsJsonObject(); api.updateObject(api.currentUser, BucketType.Data, bucketName, cinfo.getId(), obj);
Listing 23: Operation updateObject and the Usage of this Method The example usage of the method at the bottom of Listing 23 creates an object with new values for the data object which shall be updated in the CRI. If the API call is not successful, an exception is thrown.
4.10.5.2.9 Method “Delete Object” To delete data objects in the CRI, the API provides the method “deleteObject”. As mentioned before, for this the factory method shown in Listing 24 will be used. The “deleteObject” method of the API has four parameters. The first three identify the bucket from which the data object shall be deleted. The last is the object id used to identify the data object to be deleted.
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @param objectId The ID of the object being accessed * @throws RestException */ public abstract void deleteObject(ClipUser owner, BucketType bucketType, Designator bucketName, ClipObjectId objectId) throws RestException;
… CreateInfo cinfo = ...; Designator bucketName = new Designator("myBucket"); api.deleteObject(api.currentUser, BucketType.Data, bucketName, cinfo.getId());
Listing 24: Operation deleteObject and the Usage of this Method If the API call is not successful, an exception is thrown.
4.10.5.2.10 Method “Execute Query on Bucket” In order to execute a query on the database, the method “executeQuery” is provided. In Listing 25 the signature of this method is shown as well as an example of its usage.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 232 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
The bucket to query is identified by the owner, type, and name. The “lastId” attribute is used if paging is being used and a subsequent page is being read. If a subsequent page read is being performed, the value used for “lastId” is taken from the previous page read’s response. Otherwise, it is “null” for the first page read operation. The attribute “limit” is used when paging, to specify the maximum number of items to return. The query object is GSON JsonObject. The format of the JSON follows MongoDB’s specification76. The value should match the MongoDB’s “orderBy” operator77. The Attribute “findOne” is a Boolean value. If true, this disables filtering, and only returns the first match. Otherwise, the search will continue for multiple objects. This is used as a performance optimisation when only the first result is of interest.
76 https://docs.mongodb.org/manual/tutorial/query-documents/ 77 https://docs.mongodb.org/manual/reference/operator/meta/orderby/ D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 233 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
/** * @param owner The owner of the bucket being accessed * @param bucketType The type of the bucket being accessed * @param bucketName The name of the bucket being accessed * @param lastId When Paging, this is the lastId value from the previous QueryReponse * @param limit If not null, enables paging. Must be greater than 0. The maximum number of documents to return. * @param query If not present, all documents are matched. If present, query is applied in the search. * @param orderBy Optional parameter to specify the search order. * @param findOne If present and true, this disables paging and only returns the first item. * @return a QueryResponse object. * @throws RestException */ public abstract QueryResponse queryRead(ClipUser owner, BucketType bucketType, Designator bucketName, ClipLastId lastId, Integer limit, JsonObject query, JsonObject orderBy, Boolean findOne ) throws RestException;
…
JsonObject query = new JsonObject(); JsonObject subQuery = new JsonObject(); subQuery.addProperty("$gt", 10); query.add("quantity", subQuery);
QueryResponse response = api.queryRead(api.currentUser, BucketType.Data, ucketName, null, 10, query, null, false); System.out.println("Found "+response.numRead+" items."); System.out.println("Last ID " + response.lastId + " for next page."); for( ReadInfo readInfo : response.values ) { System.out.println(" "+readInfo.getValue()); }
Listing 25: API Method Signature to Execute a Generic Query on a Specific Bucket and the Usage of this Method The example usage of the method at the bottom of Listing 25 retrieves the first ten objects with the attribute “quantity” with a value greater than ten. A QueryResponse object is used to specify the returned data, with the attribute “lastId” specified, in order to be used for the subsequent query, the attribute “numRead” to specify the number of items returned, and an array of ReadInfo objects to specify the value and other meta-data (e.g. the ETag value) that was read.
4.10.6 Consumed Services The KIS component doesn’t consume any services in ACCEPT. It is primarily a component providing storage services to other components.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 234 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
4.10.7 Summary The section 4.10 explains which technology will be used to implement the KIS component based on the major design decisions taken in Chapter 4.10.1. All the project needs for data storage can be served providing different security-levels of access and the flexibility to process different datatypes. Built upon up-to-date technologies like MongoDB, KIS is a solid solution even for future usage.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 235 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
5 Mockups
5.1 Introduction A mockup78 is a usually full-sized scale model of a structure, used for demonstration, study, or testing. In software development, a mockup shows the software that will be developed; usually it shows the user interface of the program showing an example of the functionalities that will have the different screen of an application. This section shows the look and feel of the Dashboard, the SiMa and the CoOp applications, i.e., all tools that have a User Interface. These interfaces are the way to interact between Users and System. The purpose of the User Interface is to have a tool for interact with the ACCEPT System easily. It uses these mockups to develop the front-end application and to show to the final user.
5.2 Dashboard
5.2.1 Login As most application, the first screen is about authentication.
78 http://www.thefreedictionary.com/mock-up D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 236 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 41: Dashboard Login
5.2.2 Home View Once authenticated, the user reaches his “home view” where the different metrics he is interested in are displayed. Each metric is a different ‘widget’, but the “home” view” of the widget is a UI component that summarize the entire metric. The uses color-code to indicate to the users the areas that require his attention in a glance. Selecting a specific metric will open a detailed view for this metric. In this example, the users is interested in a “workflow metrics” which gives indications on how the workflow is on-time compare to the schedule, the “Checklists metric” indicating what is the quality based on on-site checklists verification, the “Thermal insulation metric” which is a sub-part of the whole checklists set, filtered out for thermal insulations. He is also registered to the ‘alert’ widget, which gives the user all the important notifications he has to react to.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 237 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 42: Dashboard Home View
5.2.3 Detail Alert View This view allows the user to consult his important pending notifications. The different parts of the view are documented in the image itself.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 238 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 43: Dashboard Detail Alert
5.2.4 Alert Answer View The next screenshot shows the ‘reply’ view. This view helps the user to react to his notifications.
Figure 44: Dashboard Alert Answer
5.3 SiMa App The mock-ups provided in this chapter show the general design for the first prototypes of the SiMaApp extensions. More detailed mock-ups can be found in the appendix.
5.3.1 Settings Extension The next Screenshots show the planned View for the Settings. In it a user can log into the system and save connection and personal data. The personal data will update certain attributes in the user profile of the user.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 239 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 45: SiMa Mock-Up - Settings Extension
5.3.2 Marketplace Extension Figure 46 shows the marketplace extension to install new extensions and uninstall already installed extensions to the SiMa device. Sensors could be installed in this manner as well. The extension shows all available extensions for the device with a short description and handles the deployment.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 240 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 46: SiMa Mock-Up - Marketplace Extension
5.3.3 Sensor Extension The sensor extension allows to connect to sensors and access the specific sensor data. Already installed sensors via the marketplace extension, which were mentioned in 240 are listed and can be connected to.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 241 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 47: SiMa Mock-Up - Sensor Extension
5.3.4 Viki Extension The Viki client just lists all Viki elements in a given proximity to the current location. It is the way to access manuals, construction plans or videos, which explain certain aspects or the status of something near the current location of the SiMa device.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 242 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 48: SiMa Mock-Up – Viki Extension 5.4 CoOp App The mock-ups provided in this chapter show the general design for the first prototypes of the CoOpApp.
5.4.1 Login The App shows the Login Screen the first time that the user opens it. This screen let the user to put his username and password. This screen is closed if the username and password are valid and match with the database entry. If this info is invalid the screen show an error tooltip message with information about this issue.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 243 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 49: CoOpApp Login
5.4.2 Main Screen The app shows the Main Screen when the login is completed successfully. The Main Screen shows the role of the user and a budget with the number of notifications pending to be reviewed. This screen has two main functionalities, the first one is show the QRCode Screen and the second one shows the Tasks Screen.
Figure 50: CoOpApp Main Screen
5.4.3 Scan Screen The QRCode Screen has four actions. The action 'Scan QRCode' uses the camera to find QRCodes and show its information. The action 'Send Location' sends the current user's location and refreshs the information stored in the app. The action 'Request EVA' shows a panel with the details of the EVA entity. The action 'Request EDA' shows a panel with the details of the EDA entity.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 244 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
Figure 51: CoOpApp Scan Screen
5.4.4 My Tasks Screen The Task's Screen is shown when the user touches the action 'Task' from the Main Screen. This screen shows the user's list task. The user can touch in a task to show its details.
Figure 52: CoOpApp MyTask Screen
5.4.5 Task Screen Each task shows a panel with five actions. The first one draws the 3D model in the screen. The action 'View EDA' shows a panel with the EDA's details. The action 'View EVA' shows a pane with the EVA's details. The action 'Attach Photo' lets the user take a photo and attach it to the task. The action 'Attach EVA' load the voice recognition engine, asks to the D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 245 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
user to record an audio file, when the audio is recorded the engine translate this audio into text and attach both, the audio and the translation to the task.
Figure 53: CoOpApp Task Screen
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 246 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
6 Conclusion and Next Steps This deliverable shows the technical approach adopted for the ACCEPT System. Each component of the architecture is described in detail, showing the best tools to develop each component and the best option chosen. It also shows the interfaces offered for the components to be used as consumed services for other components. Finally it describes mockups of the client application of the ACCEPT System. This document is the continuation of the D2.7 Architecture Definition and Functional Specification document. In the first part of the document the System Overview is showed, including the dependencies between components in the system. The next chapter provides a set of recommendations on design principles. It shows the general aspects of security, data formats, communication and interaction, extensibility and testing of a technical system. After these two chapters, section 4 talks about the technical specifications of the ACCEPT System. It shows an overview of each tool, a major decision design, and a technical comparison of the suggested tools to develop each component. Taking into account this comparison, the best technology option was selected to develop each component. Then, section 4 shows a component structure of the components, having in mind the technology selection performed. Finally, it shows the list of interfaces offered by each component to the other and the consumed services in each component of the System. The last section is about mockups. These are used to have an idea about the client components of the ACCEPT System. It shows mockups for Dashboard, SiMaApp and CoOpApp. They show the screen with the functionalities of each client tool in its respective environment: web, mobile device and smart glasses. This deliverable provides the guidelines for the development of the ACCEPT System, as it clearly identifies the technology to be used and the interfaces and consumed services for each component. During the implementation phases of the project parallel work will be performed while ensuring a seamless integration at a later stage. Finally, this deliverable will be the first step of the development phase of the project, in WP3, WP4, WP5 and WP6. The work on the development work packages will be executed based on the results of this deliverable.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 247 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
References [1] M. Fowler. Patterns of Enterprise Application Architecture. Addison-Wesley Longman Publishing, 2002. [2] Vadim Chepegin, and Stuart Campbell. “NEXOF-RA: A Reference Architecture for the NESSI Open Service Framework. ”, IBIS journal, Vol. 8, 2009, pp. 53-56. [3] Jim Webber. REST in Practice: Hypermedia and Systems Architecture O'Reilly, Beijing, 2010. [4] Sam Newman. Building Microservices. Designing Fine-Grained Systems. O'Reilly Media, February 2015.
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 248 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895
Public Technical Specification ACCEPT WP2 and Mockups
7 Annex
IDM - ER-Diagram
D2 8 - Technical Specification and Mockups - Document Date: Page: For Approval 1.0.docx Version: 1.0 2015-12-28 249 / 249 http://www.accept-project.com/ Copyright © ACCEPT Project Consortium. All Rights Reserved. Grant Agreement No.: 636895