A practical guide to app development for the FIspace Platform

(1)

Deliverable D600.1.1 & D600.1.2

A practical guide to app development for the

FIspace Platform

WP 600

Project Acronym & Number: FInish – 632 857

Project Title: Food Intelligence and Information Sharing for Business Collaboration enabled by the Future Internet

Funding Scheme: Collaborative Project - Large-scale Integrated Project (IP) Date of latest version of Annex 1: 27.05.2014

Start date of the project: 01.09.2014

Duration: 24

Status: Final

Authors: Peter Einramhof, Norman Gülcü

Contributors: Harald Sundmaeker

Document Identifier: FInish-D600.1-PlatformConfigMaint-FINAL-V001.docx

Date: 21.10.2015

Revision: 10

(2)

Project Summary

This project will utilise technologies of the Future Internet PPP programme to enable the development and operation of intelligent systems for supply chains of perishable products such as food and flowers. The project includes an ecosystem that brings together: i) business needs of user communities and ii) creative ideas & technological opportunities of software SMEs and web-entrepreneurs. The corner stones of this ecosystem are regional clusters that include close synergies with regional developments & policies that are embedded in European networks. FInish will use the FIspace platform as a basis and aims to drastically enlarge the number of services/applications available in the FIspace store by involving through open calls SMEs and web-entrepreneurs as developers. As such, the Finish project will enable seamless B2B collaboration and it will empower companies including SMEs and new players to set up and partici-pate in new regional, horizontal and vertical collaboration quickly and at minimal costs. By doing this, FInish wants to give an impulse to the shift from cost-driven to value-based, information-rich supply chains, which will significantly increase the added value, competiveness and sustainability of the domain. More specifically, FInish aims to:

1. Empower small & innovative ICT players to develop high-quality and high-impact solutions for food and flower supply chain networks based on technologies of the FI-PPP programme

2. Develop a large set of innovative and technologically challenging services and applications for virtualisation, connectivity and intelligence of food and flower supply chain networks

3. Implement and validate the technologies and concepts developed in the FI-PPP

4. Support SMEs in creating high-impact apps with Future Internet applications and helping to mar-ket their apps cross border in specialised EU marmar-kets and beyond

5. Ensure business value of services/applications for collaborative business networks in food & flower industry

Project Consortium

 ATB Institut für angewandte Systemtechnik Bremen GmbH; Germany  DLO Stichting Dienst Landbouwkundig Onderzoek; The Netherlands  Euro Pool System International (Deutschland) GmbH; Germany  CentMa GmbH; Germany

 iMinds; Belgium

 CBHU Campden BRI Magyarország Nonprofit Kft.; Hungary  DCS Fondazione Democenter-Sipe; Italy

 EBILTEM Ege University Science and Technology Centre; Turkey

More Information

Harald Sundmaeker (coordinator) e-mail: [email protected] phone: +49 (421) 22 09 253

ATB Institut für angewandte Systemtechnik Bremen GmbH Wiener Straße 1; 28359 Bremen

(3)

Dissemination Level

PU Public X

PP Restricted to other programme participants (including the Commission Services) RE Restricted to a group specified by the consortium (including the Commission Services) CO Confidential, only for members of the consortium (including the Commission Services)

Document Summary

This document is the accompanying report to the deliverables D600.1.1 and D600.1.2 FInish Platform Configuration and Maintenance, which are of the nature “Prototype”.

It is primarily intended for software developers who want to use the FIspace Platform as basis for their solutions and that are funded by the FInish accelerator. Its main focus lies on providing a practical guide for app development under FIspace. Furthermore, it motivates the reasons why FInish has chosen to promote the FIspace Platform among the available FIWARE technologies as target “ecosystem” for the envisioned solutions for supply chains of perishable products such as food and flowers. The document also provides information about the current and planned availability of the FIspace Platform, and what means of support FInish provides to those developers who have chosen FIspace.

(4)

Abbreviations

ACSI Artifact-Centric Service Interop-eration

AJAX Asynchronous JavaScript and XML

API Application programming inter-face

App Software Application

B2B Business-to-Business module of the FIspace Platform

BCM Business Collaboration Module CORS Cross-Origin Resource Sharing CSS Cascading Style Sheet

D Deliverable

DoW Description of Work

EC European Commission

EE

Experimentation Environment – public instance of the FIspace platform

e.g. Exempli gratia = for example EPM Event Processing Module

EU European Union

FIA Future Internet Assembly FI PPP Future Internet Public Private

Partnership

FP7 Framework Programme 7

GA Grant Agreement

GE

Generic Enabler – application domain independent FIWARE software module

GUI Graphical User Interface HTML HyperText Markup Language HTTPS Hypertext Transfer Protocol

Secure

ICT Information and Communication Technology

IDE Integrated Development

Envi-ronment

i.e. id est = that is to say IP Internet Protocol

M Month

PC Personal Computer

PDF Portable Document Format PIA Product Information App

REST REpresentational State Transfer RTD Research and Technological

Development

SaaS Software-as-a-Service

SDI System & Data Integration mod-ule of the FIspace Platform SDK Software Development Kit SE

Specific Enabler – domain-specific FIWARE software mod-ule

SME Small and Medium Sized Enter-prise

SPT Security, Privacy & Trust module of the FIspace Platform

ST Sub-Task

T Task

URI Uniform Resource Identifier URL Uniform Resource Locator

WE Web entrepreneur

WP Work Package

XML Extensible Markup Language XSD XML Schema Definition

(5)

List of Figures

Figure 1: Extension mechanisms of the FIspace Platform. ... 12

Figure 2: Example for the "typical" architecture of a FIspace application and its connection with the FIspace Platform ... 13

Figure 3: Example of three app instances (PIA) that are part of a business collaboration facilitated by FIspace. ... 14

Figure 4: FIspace Home Screen ... 15

Figure 5: Functionality for FIspace Application Developers and Business Architects ... 16

Figure 6: FIspace BitBucket Core Repository ... 17

Figure 7: Fork of the FIspace Core Repository ... 18

Figure 8: Clone FIspace Core Repository using TortoiseHG ... 19

Figure 9: BitBucket – User Repository ... 20

Figure 10: Pull Request for Integration into Core Repository ... 20

Figure 11: Capability Creation ... 22

Figure 12: Creating OAuth Client ... 23

Figure 13: Retrieving keycloak.json File ... 23

Figure 14: FIspace frontend after login - here you can find the link to your dashboard. ... 27

Figure 15: The empty dashboard - here you can upload an application to your local "marketplace". ... 27

Figure 16: Local marketplace - here you can select widget to be uploaded (from your local PC). ... 27

Figure 17: The widget in the local market place. The highlighted button leads back to the dashboard. ... 28

Figure 18: Back on the dashboard. Here you can add widgets from the local marketplace. ... 28

Figure 19: Adding a widget to the dashboard. ... 28

Figure 20: Hovering the mouse pointer over the widget's frame will reveal the widget menu. ... 29

Figure 21: Settings of the widget, which allows accessing the user-defined preferences. ... 29

Figure 22: The values of the widget’s preferences as defined in the file "config.xml" can be edited. ... 29

Figure 23: Create a Business Process Template ... 30

Figure 24: Choose a Template for a Business Process ... 31

Figure 25: Select Capabilities for a Business Process ... 31

(7)

1 Introduction

The FInish accelerator is funding projects proposed by SMEs and start-ups/web entrepreneurs who pro-pose to develop new software applications utilising FIWARE technologies, and specifically the FIspace platform. The intended outcome is the development and operation of intelligent systems for dynamic sup-ply chains of perishable products such as food and flowers. More specifically, the envisaged develop-ments shall address the domains of agri-food supply chains, transport, logistics, food manufacturing and processing, and/or retail of food/flowers. Potential synergies with other fields such as smart cities, health awareness and/or multimedia can lead to additional potential of a proposed solution.

To facilitate provisioning of these solutions (software services) to a critical mass of developers and end-users, FInish promotes the usage of the FIspace platform, which in turn shall increase the number of ser-vices/applications available in the FIspace store. It is the objective of FInish to enable seamless B2B col-laboration for end-users and to empower SMEs and new players to set up and participate in new regional, horizontal and vertical collaboration quickly and at minimal costs. In doing so, FInish wants to generate an impulse to the shift from cost-driven to value-based, information-rich supply chains, which will significantly increase the added value, competiveness and sustainability of the domain.

In order to achieve these goals, FInish needs to empower its funded SMEs and start-ups/web entrepre-neurs to develop high-quality and high-impact solutions for food and flower supply chain networks using FI-WARE technologies as well as a large set of innovative and technologically challenging services and applications for virtualisation, connectivity and intelligence of food and flower supply chain networks. More concretely, FInish

 Provides its funded projects with access to the required information, tools and services

 Coordinates access to FIWARE technology and experimentation infrastructure for its funded pro-jects, and especially FIspace Platform access

 Facilitates configuration and maintenance of the FInish/FIspace Platform

1.1 Scope of this document

This document is part of the deliverables D600.1.1 and D600.1.2 FInish Platform Configuration and Maintenance. It is primarily intended for software developers who want to use the FIspace Platform as basis for their solutions that are funded by the FInish accelerator. It motivates the reasons why FInish has chosen to promote the FIspace Platform among the available FIWARE technologies as target “ecosys-tem” for the envisioned solutions for supply chains of perishable products such as food and flowers. This document also provides information about current and planned availability of the FIspace Platform, and what support FInish provides to those developers who have chosen FIspace. The main focus, however, lies on providing a practical guide for app development under FIspace.

1.2 Intended target audiences

This document is intended for the following target audiences:

 Software-developers funded by FInish: as a reference manual for implementing FIspace-based software solutions and overview of the support that FInish is offering for getting started with devel-opment using FIspace and for solving technical problems.

 FInish project partners: manual for guiding and mentoring software developers who are basing their solutions on the FIspace Platform.

 European Commission Services: for the purpose of documentation and allowing evaluation of the FInish accelerator’s approach and progress or achievements, respectively.

 Other Programme Participants: especially other accelerator projects whose sub-granted projects are planning to base their solutions on the FIspace Platform.

 The general public: more specifically, software-developing companies who have not participated in any way in the FI-PPP Programme yet, but who might be interested in getting started with FIWARE technology, and in particular with the FIspace Platform.

(8)

1.3 Structure of the document

The content of this document is structured as follows: Section 2 motivates why the FInish accelerator has chosen to promote specifically the use of the FIspace Platform among all available FIWARE technologies for solutions funded in the course of FInish.

Section 3 provides an overview of the means of support that the FInish accelerator is offering to its fund-ed software-developing SMEs and start-ups with respect to accessing and using FIWARE technology and most notably the FIspace Platform.

The main focus and contribution of this document is a practical guide to app development for FIspace, which is described in Section 4. This guide is a “snapshot” reflecting the current status of app develop-ment that is aligned with the current release of the FIspace Platform.

(9)

2 The FIspace Platform

There is a wide range of FIWARE technology available, upon which application developers can base their solutions. Generic Enablers (GEs) provide application domain independent functionality such as identity management, visualisation or data storage. Built on top of subsets of these GEs are (domain-) Specific Enablers (SEs), which focus on business/application domains such as transport, logistics, agri-food, smart cities or manufacturing. Among these SEs, the FIspace Platform stands out since it is more than “just” an SE – it is a homogeneous platform for business to business collaboration. The public FInish doc-ument D200.4.1 Experimentation Infrastructure Mapping and Guideline provides a more detailed over-view of the available FIWARE technology and experimentation infrastructure.

2.1 Why FInish has chosen to promote the FIspace Platform

As stated in the introduction, the FInish accelerator is funding SMEs and start-ups/web entrepreneurs who propose to develop new software applications utilising FIWARE technologies. These new applica-tions shall provide soluapplica-tions for the domains of agri-food supply chains, transport, logistics, food manufac-turing and processing, and/or retail of food/flowers. The objectives are to enable seamless B2B collabora-tion for end-users and to empower SMEs and new players to set up and participate in new regional, hori-zontal and vertical collaboration quickly and at minimal costs.

The following aspects of the FIspace Project make solutions based on the FIspace Platform seem ideal for achieving the aforementioned objectives:

 Focus on collaborative workflows and business-to-business collaboration  Availability of an SDK to speed up the development of FIspace-based solutions  FIspace Store, where developers can monetize their own solutions

 A set of initial and domain-specific apps providing functionality that can be re-used and combined by new FIspace apps

 Fresh Fruit & Vegetables Quality Assurance Trial and Flowers and Plants Supply Chain Monitor-ing Trial validatMonitor-ing the concept of the FIspace Platform

 Collection of standards of a wide range of business domains, among them those targeted by FIn-ish, upon which developers of applications/solutions shall build

The document D200.1 Consolidated FI Architecture for Perishable Supply Chains published by FInish discusses above listed points in more depth.

2.2 Current offerings of the FIspace Project for app developers

The FIspace Project has already released a preliminary public instance of a FIspace Experimental Envi-ronment for application developers, which is being updated periodically based on the latest development cycle of the platform. In other words, since the development of the platform is not finished yet, not all of the intended platform features are currently available to application developers, but are planned to be added in the upcoming release. A list of implemented features of the most recent deployed Experimental Environment is available on the FIspace website. In order to provide tool support to app developers for implementation deployment and configuration of FIspace-based solutions, the FIspace Project has re-leased an SDK (Software Development Kit). There is documentation available via the FIspace website and the BitBucket site of FIspace. This documentation is already quite extensive and being continuously updated. However, the information that is most relevant for app developers is not centralised yet. This is the reason why the technical team of the FInish accelerator has created a first version of a FIspace app developer guide (see Section 4) in close collaboration with the FIspace Platform developer team.

2.3 Planned FIspace Platform releases

According to the most recent planning of the FIspace Project, there will be one more public release of the platform providing new features for app development, deployment and testing. The last release before the planned commercialisation of the platform (see section 2.4) is planned for mid-November. Releases of the FIspace Platform will be accessible in the form of the aforementioned Experimentation Environment.

(10)

2.4 Commercialisation of FIspace – the FIspace Foundation

The FInish accelerator is funding projects which develop solutions that shall have real impact and com-mercial success in the targeted domains of perishable food and flowers. A prerequisite for that is the availability of a commercial instance of the “ecosystem” based on which those solutions have been de-veloped. The FIspace Project is a research project, and thus its main outcome – the FIspace Platform – is not a commercial product yet. Therefore, efforts towards a commercialisation of the platform by the re-cently established “FIspace Foundation” are underway. Updates about the status and progress of the FIspace Foundation will be published the FIspace website.

(11)

3 Support by FInish for FIspace app developers

The FInish accelerator offers several means of support for developers of FIWARE technology based solu-tions (i.e. using FIWARE Generic Enablers, the FIspace Platform, or a mix of both) in the course of a project funded by FInish:

 Mailing list: [email protected] is dedicated to FIWARE technology related problems and questions. Members of the technical team of FInish receive emails that are sent to this mailing list. In case the reported problem or question can be answered by the FInish team, they will respond directly. Otherwise the problem or question will be relayed to the FIspace sup-port staff or FIWARE coach that have been assigned to the FInish accelerator, and the FInish team will forward the answers for the support staff or coach to the developers.

 Weekly Oracle online meetings: Every Friday, starting at 14:00 CET, FInish is hosting a We-bex-based online meeting for its funded software-developing companies. For every such meeting, an invitation is sent via email. This meeting is attended by several members of the FInish team, who answer technical as well as oranisatorial questions (or relay them appropriately in case they cannot be answered immediately).

 Advanced accounts for FIspace/ FI-Lab: Every user can register for a basic account of the ex-perimentation infrastructure of the FIspace Platform or FI-Lab. Such basic accounts, however, al-low only limited access to the features supported by both experimentation infrastructures. Only advanced accounts allow full access. However, the currently available (infrastructure) resources for experimentation are limited, so that only those developers who are funded by a FIWARE ac-celerator get access to advanced accounts. FInish vouches for its funded developers so that they are granted access.

 Provide training material and documentation about the FIspace Platform for app developers and business architects – updated according to the current development status of the FIspace Platform. Most notably FInish has developed a practical step-by-step guide for FIspace app de-velopers, including an example application, which serves as basis for that guide.

 Contact with app developers of the FIspace Project: In the course of the FIspace Project a number of initial and domain-specific apps have been developed, with the intention of providing a certain baseline of functionalities that other app developers using FIspace can reuse and build upon. These initial and domain-specific apps have different levels of maturity and conditions for their usage. When required, FInish establishes the contact between the funded software develop-ing companies and the app developers of the FIspace project.

(12)

4 A practical guide to app development for FIspace

This section provides a practical guide to developing apps for the FIspace Platform. The guide in this document represents a snapshot reflecting the current status of app development under FIspace.

The following sections first give an overview of the developer roles in FIspace (section 4.1) and of the architecture of a “typical” FIspace app as well as its connection to the FIspace Platform (section 4.2). This overview is followed by a step-by-step example of a FIspace app (section 4.3) addressing both implemen-tation and connection to FIspace, and by a step-by-step example of configuring a workflow in the FIspace Platform that makes use of the functionality offered by apps (section 4.4).

4.1 The extension mechanisms of FIspace and resulting developer roles

The FIspace Platform is an extensible Software-as-a-Service (SaaS) Platform for business-to-business (B2B) collaboration across organizational boundaries. Extensibility is achieved in two ways (Figure 1):

1. New value-added functionality can be added in the form of FIspace apps. In the context of FIspace functionality is referred to as “(business) capabilities”. These capabilities can be used by business processes that are being executed on the FIspace Platform.

Capabilities are categorised in business domains such as logistics or agriculture, and should pro-vide reusable functionality within their business domain.

2. Configurable collaborative workflows that make use of (subsets of) aforementioned capabili-ties, and also of external systems and services.

Figure 1: Extension mechanisms of the FIspace Platform.

FIspace applications will not be built towards a given programming interface (API), therefore they are different from typical smartphone apps. The model of FIspace Applications is much closer to the software service or the component based software-engineering model, where reusable features are offered through interfaces defined by the services/components. Regarding this software development approach the FIspace platform can be extended by functionality which is provided by applications. FIspace applica-tions provide functionality. Interested parties can select, combine and mash-up services provided by FIspace applications into more complex service compositions. The separation of functionality and work-flow leads to two roles with respect to the development of solutions based on the FIspace Platform:

1. App developer: implements FIspace apps that provide one or more (business) capabilities. Such apps usually consist of a frontend (widget) and a backend. Only the latter can implement capabili-ties and thus constitutes the “heart” of a FIspace app.

(13)

2. Business architect: configures workflows on the FIspace platform that model the business pro-cesses required by the (business) end users, and that make use of the capabilities provided by one or more apps – these apps can be instances of the same type and/or instances of different types of apps.

4.2 Typical architecture of an app and its connection to the FIspace Platform

A “typical” FIspace app consists of a web-based app backend and a frontend (see Figure 2). The backend implements the business logic and provides storage of data (if needed). It is deployed outside the FIspace Platform and connects to the latter via the FIspace Platform’s SDI – System and Data Inte-gration module. The backend also makes its business capabilities available to business processes via SDI.

Figure 2: Example for the "typical" architecture of a FIspace application and its connection with the FIspace Platform

The app can not only offer its functionality but also make use of the functionality provided by other FIspace apps via SDI and in the course of business processes. It should be noted that only messaging (notifications) between apps takes place over the FIspace Platform, but the exchange of data (e.g. prod-uct information, sensor data, etc.) happens outside of FIspace and directly between the apps. FIspace only provides the notification about the availability of data and the link to the resource – Figure 3 shows an example of three instances of a FIspace app (PIA) that is used to exchange product information be-tween actors of the food supply chain in the course of a business process facilitated by FIspace.

(14)

Figure 3: Example of three app instances (PIA) that are part of a business collaboration facilitated by FIspace.

The FIspace Platform’s module SPT – Security, Privacy and Trust module – is responsible for identity management as well as for authentication and authorisation of FIspace users and apps. SPT uses OAuth2, and from the perspective of SPT an app backend is an OAuth client.

The app frontend is deployed inside the FIspace Platform, more specifically, on the user’s dashboard that is part of the FIspace Frontend. The app frontend can access information about the currently logged in user and store/read configuration information via the FIspace Frontend. The connection with the app backend is established via using RESTful web services (and also web sockets) that the backend has to provide.

4.3 Step-by-step guide for FIspace app developers

The following sections describe the steps that are necessary to develop a FIspace application and to connect it to the FIspace Platform.

4.3.1 Preparation

4.3.1.1 Installation of development tools

For application development the Java Development Kit version 1.8 update 25 or higher and a develop-ment environdevelop-ment supporting Java is required. Furthermore a BitBucket account is needed for accessing the FIspace core repository.

For downloading the FIspace core source code a source control management tool is recommended, e.g. Mercurial. Apache Maven as a software project management tool is also required for the build process of the source code.

Prerequisites for FIspace Application development:

 Oracle Java Development Kit version 1.8 update 25 or higher, download here

 An IDE (integrated development environment) supporting Java, e.g.Eclipse, NetBeans or In-telliJ IDEA

 BitBucket account (see Section )

(15)

 FIspace Studio/SDK, online documentation is available in the FIspace Wiki describing the steps necessary to install the FIspace SDK and/or the FIspace Studio

 Mercurial, a free, distributed source control management tool

o TortoiseHG, a Windows shell extension and a series of applications for the Mercurial dis-tributed revision control system

 Apache Maven, a software project management and comprehension tool

 YggClient, a library which facilitate the communication to SDI and integrate security functionalities  PuTTY, a free implementation of Telnet and SSH for Windows and Unix platforms

4.3.1.2 Registration at the FIspace Experimentation Environment

Basic account

The FIspace Experimentation Environment (EE) is a public instance of the FIspace platform. After the registration of a user and login with the provided credentials, the platform can be accessed and the home screen (Figure 4) will be loaded. Besides default users there are two other types of user roles (i.e. appli-cation developer and business architect) who have access to additional platform functionality (Figure 5).

Figure 4: FIspace Home Screen

Upgrading to an application developer and/or business architect account There are 3 different user types available on the FIspace platform:

 Default (End) Users: actual (industry) users (such as supply chain actors) of the collaboration services and applications provided by FIspace.

o Those users will be supported in their daily business activities, with special focus on their interaction and collaboration with business partners. Examples of those users include farmers, shippers, freight forwarders, cargo carrying airlines, and regulatory agencies.  Application Developers: actual software and system providers who offer “packaged” /

compo-nentized solutions and applications in form of FIspace applications.

o Application developers have access to security- and data integration-related functionality provided by the platform, like creating OAuth clients for applications and defining

(16)

applica-o Business architects define customized collaborative workflows and connect those work-flows with FIspace Applications and backend systems.

By default users of the FIspace platform do not have access to application developers- or business archi-tects-related functionality. To access those special functionality like for application developers the user has to request a specific user role from the FIspace user management by email to [email protected]. As part of the request necessary information is:

 the user account to be configured (i.e. registered user name and email address used for the reg-istration)

 the person and/or company responsible or related to this user account

 the project or accelerator name funding the application development related to this user account  the requested role (i.e. Application Developer, Business Architect, or both)

Figure 5: Functionality for FIspace Application Developers and Business Architects

4.3.1.3 Registration at BitBucket and Discovery of Core Repository

BitBucket Account

A BitBucket account is needed for getting access to the FIspace core repository. The core repository cannot be accessed directly; therefore you have to create a fork to use and contribute to the project, e.g. by implementing new messages to be used by application capabilities.

To create a BitBucket account go to the Bitbucket homepage and follow the “Get Started” instructions.

Fork of the FIspace Core Repository

With a fork you can work on a completely separate copy of the project without affecting any other devel-opers. Changes made and committed by you only affect your working copy until you send a pull request and your changes are applied in the FIspace core repository.

(17)

Figure 6: FIspace BitBucket Core Repository

For forking go to the FIspace core BitBucket page and click on “Fork” in the left menu (Figure 6) and enter a description about the intention of this fork (Figure 7) on the next screen. Once you have created a fork of the core repository you can check it out.

(18)

Figure 7: Fork of the FIspace Core Repository

4.3.2 Creation of an application backend

4.3.2.1 Development Environment Configuration

Checkout your Fork of the FIspace Core Repository

For checking out your fork you can use either the command line client, e.g. on Linux machines, or a GUI for Mercurial (TortoiseHG). After checking out the project it can be opened/imported into an IDE, used and changed.

Check out FIspace core source code using the command line (see commands below): 1. Create a destination directory for the check out

2. Change to the destination directory

3. Clone your fork by using your BitBucket username in the “hg clone” command mkdir /fispaceCore

cd /fispaceCore

hg clone ssh://[user]@bitbucket.org/fispace/core

Check out FIspace core source code using TortoiseHG (Figure 8): 1. start TortoiseHG

2. Choose “Clone Repository…” in the “File” menu

3. Enter source: https://[user]@bitbucket.org/fispace/core, use your BitBucket username 4. Choose destination for the downloaded repository

(19)

Figure 8: Clone FIspace Core Repository using TortoiseHG

Committing Changes and Sending a Pull Request

1. Use Mercurial or TortoiseHG to commit your changes to your repository copy on BitBucket. After your changes have been committed you have to open your repository on BitBucket which is available via https://bitbucket.org/[user]/core using your username (Figure 9).

2. Click on the “Pull Requests” item in the left menu and on “Create pull request” on the next screen in the upper right corner

3. On the final pull request screen enter a description about the intention and content of this pull re-quest (Figure 10).

4. As Reviewers add the following user names for informing the platform developers about your de-sired changes on the core repository:

a. perezdf b. jhitado c. monezz

5. Click on the “Create pull request” button to send your request to the reviewers.

6. Once the reviewers have been informed about your request they will start conversation via the BitBucket comments of the pull request or other channels if needed. When the pull request is ac-cepted or rejected you will be informed via BitBucket.

(20)

Figure 9: BitBucket – User Repository

(21)

4.3.2.2 Connection to FIspace (SDI)

FIspace applications have to register capabilities for enabling business architects to use such provided functionality within business processes. To do this the message types to be used by those capabilities have to be implemented in the FIspace core source code. Application developers have two options to define capability types:

1. Choose existing message types already implemented and integrated into the FIspace core im-plementation and use them to define message types of capability types.

2. Create new message types (i.e. not already integrated in the FIspace core), upload them to the FIspace Bitbucket, send a pull request and go on with step 1.

To discover available message types checkout the FIspace core (see Section 4.3.1.1) open the checked out project in an IDE, e.g. Eclipse, and look into the “api” project. On the path api/src/main/resources/eu/schema/domain you can find folders for different domains and areas, e.g. “ag” for agriculture of “lg” for logistics. Within each of those domain folders there are XSD (XML Schema) files for specifying how to describe the elements in an XML (Extensible Markup Language) file. For example in the “lg” folder for the business domain you can find two XSD files:

 LGMessages.xsd: In this file the message types and their content are defined which are used by FIspace and FIspace applications for communication and information exchange. These message types have to be an extension of either the “ygg:ResponseMessage” or "ygg:RequestMessage". They also can be extended from a message type which is based on the “ygg:ResponseMessage” or "ygg:RequestMessage".

 LGModel.xsd: Here you can define data types to be used in message types and also message types to be used to extend from in the LGMessages.xsd.

For our example case we prepare requests for the box count on a pallet for a given box type by defining a request message (i.e. "ExampleBoxCountRequest”). In turn we define an appropriate response message (i.e. "ExampleBoxCountResponse"). Because we use only string and no data types which are not already defined, there is no need to edit the LGModel.xsd. See both message definitions below.

Example message for requesting possible box count on pallet: <xsd:element name="ExampleBoxCountRequest">

<xsd:complexType>

<xsd:complexContent>

<xsd:extension base="ygg:RequestMessage"> <xsd:sequence>

<xsd:element name="BoxType" type="xsd:string"/> </xsd:sequence>

</xsd:extension> </xsd:complexContent> </xsd:complexType>

</xsd:element>

Example message for providing possible box count on pallet: <xsd:element name="ExampleBoxCountResponse">

<xsd:complexType>

<xsd:complexContent>

<xsd:extension base="ygg:ResponseMessage"> <xsd:sequence>

<xsd:element name="BoxCount" type="xsd:string"/> </xsd:sequence>

</xsd:extension> </xsd:complexContent> </xsd:complexType>

</xsd:element>

(22)

Application developers and business architects have access to additional functionality of the FIspace platform. This functionality is accessible via buttons in the frontend (see Figure 5 in Section 4.3.1.2). The “Developer Zone” deals with OAuth clients for applications which are needed for connecting applications with the FIspace platform. The “Business & Capabilities” screen deals with the creation and editing of abstract capability types and business process templates as well as instances of them (i.e. capabilities and business processes).

To make use of functionality provided by FIspace applications business architects (i.e. FIspace users with the business architect role) can integrate capabilities within business processes. Such capabilities have to be created by application developers (i.e. FIspace users with the application developer role) using the FIspace frontend. On the “Business & Capabilities” screen a capability has to be created by either choos-ing an existchoos-ing type or creatchoos-ing a new one. Users who want to create a capability need to provide:

 a description of the capability to be provided

 an URI for accessing the capability (i.e. the REST web service implementing this capability)  a capability type chosen from a list of available types

Figure 11: Capability Creation

The created capability will be registered at the FIspace platform and can be integrated within business processes by business architects.

4.3.2.3 Authentication of the backend (SPT)

Due to the public usage of the platform provide access to the keycloak admin console to app developers cannot be provided. Therefore, Fispace provides administrative functionalities to register new apps which need to implement OAuth 2.0 standard protocol. Additionally, there is a library called YggClient which facilitate the communication to SDI and integrate security functionalities. The FIspace Frontend offers these operations by a page called “Developers Zone” on the left side of the main menu. User must have "app developer" role in order to have access to this operations (see section 4.3.1.2 for upgrading to an application developer and/or business architect account). An overview of the SPT is available on the FIspace Wiki, specifically the PDF document linked at the end of the Wiki page.

(23)

Figure 12: Creating OAuth Client

In the developers zone (Figure 12) fields for the name of the client, Access type (in case you are using Javascript Adapter must be "public") and set of redirection URLs have to be filled. Based on experience with app developers, they tend to feel being forced to use a public Internet IP, this is wrong, you can re-quest to register a localhost URL. Only take into account that the port you are using (e.g. locahost:8080, localhost:8081...) should match. After configuring an app in the developers zone, the “keycloak.json” file for configuring the respective app can be retrieved (Figure 13).

Figure 13: Retrieving keycloak.json File

After retrieving your key and secret values the keycloak.json file used in the app backend needs to be updated. This json file contains all necessary information for a specific case, do not hesitate to adapt the way you are retrieving the value of your properties following similar format of this file which will make it much easier to adapt new configuration files:

(24)

{ "realm" : "fispace", "realm-public-key" : "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGE GoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p 2vjO2NjsSAVcWEQMVhJ31LwIDAQAB", "auth-server-url" : "http://auth.ee.fispace.eu:8080/auth", "ssl-required" : "none", "resource" : "fispace-backend-example", "credentials" : { "secret" : "38e95169-fe68-4750-814d-5d2620d42014" } }

4.3.3 Creation and deployment of a FIspace widget (app frontend)

Section 4.3.3.1 describes what a FIspace (application) widget is as well as its structure. Section 4.3.3.2 sketches how a widget is connected to an associated (application) backend. Both sections also highlight some practice-relevant details in the example code. Section 4.3.3.3 describes how to upload the widget to the FIspace Platform’s frontend, and how to deploy it on the user dashboard. Finally, section 4.3.3.4 shows how the widget can be configured using mechanisms of the FIspace frontend. Please note that the FIspace SDK supports app developers in the creation and upload of widgets, specifically by providing templates as well as an editor for the configuration XML file.

4.3.3.1 Basic information about FIspace widgets and sample code

An application frontend that is deployable in the FIspace Platform’s frontend (which is based on the Wire-cloud GE1) needs to be a “widget”. Such a widget is implemented in HTML5, CSS and JavaScript. Fur-thermore, there is an XML file (“config.xml”), which will be described further below. Typically, the code of a widget is organised in the following folder structure (bold and underlined names represent folders): ┌─ css │ ├─ style.css ├─ doc │ ├─ catalogue.html ├─ img │ ├─ catalogue.png │ ├─ catalogue_iphone.png ├─ js │ └─ script.js ├─ index.html └─ config.xml

To produce a widget, these files/folders need to be ZIPed2, resulting, for instance, in a file “widget.zip”. Although not absolutely necessary, the file ending should be changed from “.zip” to “.wgt”. In our example this yields the file “widget.wgt”.

The red file names in the box above are the aforementioned HTML5, CSS, JavaScript, and XML files of the widget (of course, there can be additional files such as styling, images and scripts). The blue file names provide the widget’s icons and short description (documentation) that are displayed after the widget has been uploaded to the FIspace Platform’s frontend.

JavaScript represents the widget’s “active” part (frontend logic), which takes care of user inputs and also connects to the application backend (typically using jQuery AJAX).

There sample code of the example FIspace widget is available as download. After downloading, create a folder und unpack the file in that folder. You can view widget directly in a browser by clicking on the file “index.html”. Since the widget is in this case not executed within the FIspace frontend, you should get a

1

(25)

message that it couldn’t find an instance of Wirecloud. This is due to the fact that the sample widget tries to read some configuration information (see section 4.3.3.4) from the FIspace frontend’s Wirecloud. The GUI of the widget consists of two parts. The upper part shows the settings for accessing the (sample) application backend that is described in section 4.3.2. The lower part allows exchanging data with afore-mentioned backend. From a dropdown list one of several box types can be selected. When pressing the submit button, the selection is sent to the backend. The backend computes how many boxes of the se-lected type can be put on a pallet and returns that number to the widget, which finally displays it.

The file “config.xml”

The (compulsory) file “config.xml” provides metadata that is necessary for the widget’s upload and de-ployment. Also, widgets might need some settings that should not be hard-coded within the widget itself. An example is the URI of an application backend that the widget is connected to (in this case the widget would play the role of an application frontend). It is possible to store (and change) such settings in the frontend of the FIspace Platform. In order to do so, the names of the settings’ properties need to be de-clared in a dedicated section of the file “config.xml”. Below is an excerpt from the file “config.xml” that is part of the (above) downloadable FIspace widget example – for reference, the line numbers are provided, too.

30  31 <Platform.Preferences>

32 <Preference name="backend_ip" type="text" description="Backend IP address" label="Backend IP" value="127.0.0.1" />

33 <Preference name="backend_port" type="text" description="Backend port" label="Backend Port" value="8080" />

34 <Preference name="backend_https" type="text" description="Use HTTPS for backend" label="Backend HTTPS" value="0" />

35 </Platform.Preferences>

In the example three properties have been declared: “backend_ip”, “backend_port” and “backend_https”. These properties define the IP address and port number under which the application backend can be accessed, and whether a secure connection is to be used.

The excerpt from the file “script.js” that is part of the downloadable FIspace widget example shows how a widget can access the values of the preferences. First, the widget has to check whether there it has been deployed in the FIspace frontend and thus in Wirecloud. If so, there is an object “MashupPlatform”, which represents the instance of Wirecloud. Otherwise it’s undefined – see line 79 in the listing below.

Given an object “MashupPlatform” exists, the values of the defined preferences can be accessed by us-ing MashupPlatform.prefs.get(‘name_of_the_property’), where “name_of_the_property” is to be replaced by an actual name as declared in the preferences section of the file “config.xml”. In our concrete example (i.e. the FIspace widget example) those names are “backend_ip”, “backend_port” and “backend_https” (see lines 83-85 in the listing below). Besides preferences, there’s more information3

available in the Wirecloud instance (of the FIspace frontend). For instance, the user name of the currently logged in user – see line 81 in the listing below.

75 function wirecloudGet() { 76 try {

77 // Check if there is an instance of Wirecloud accessible by the widget. 78 bWirecloud = false;

79 if (typeof MashupPlatform !== 'undefined') {

80 // If there is an instance, get the username of the currently logged in user. 81 backendUser = MashupPlatform.context.get('username');

82 // Get the IP address, port number and HTTPS status of the backend from Wirecloud. 83 backendIP = MashupPlatform.prefs.get('backend_ip');

84 backendPort = MashupPlatform.prefs.get('backend_port');

85 if (MashupPlatform.prefs.get('backend_https') === '0') backendHTTPS = false; 86 else backendHTTPS = true;

87 bWirecloud = true; 88 }

(26)

89 // At this point, no Wirecloud instance has been detected. 90 else {

91 bWirecloud = false;

92 alert('Could not find a WireCloud instance!'); 93 }

94 } catch(err) {

95 alert('Encountered error(s) when reading the preferences from the Wirecloud instance!'); 96 }

97 }

4.3.3.2 Connection of widget and application backend

The widget exchanges data with the application backend by invoking RESTful web services that the backend needs to provide. The widget uses an XMLHttpRequest to access a web service. A comfortable way of implementing such request is using jQuery AJAX4 (Asynchronous JavaScript and XML), which is also used for our sample FIspace widget. The (partial) listing below shows such a request to the backend. Line 161 shows sending a POST request, while lines 174 and 178 show the functions that are being asynchronously invoked on successful completion (“.done()”) or in case of an error (“.fail()”).

It should be pointed out that a commonly encountered issue is the one of “Cross Origin Resource Shar-ing”, or short CORS, where the browser and/or the backend refuse to execute the XMLHttpRequest. For more information see the following links: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing and http://en.wikipedia.org/wiki/Cross-site_request_forgery. On the side of the widget, lines 166-171 in the listing below take care of the CORS issue.

Furthermore, if HTTPS is to be used for the requests that the widget sends to the backend, a certificate is required. This can either be a paid, trusted certificate, or, a “hand-crafted”, which, however requires man-ual intervention (i.e. make the browser accept the certificate) and might cause other technical issues. 160 // Send the request to the backend (using jQuery AJAX).

161 $.ajax({ 162 url: url, 163 type: 'POST',

164 data: JSON.stringify(obj), 165 contentType: 'application/json', 166 xhrFields: {

167 withCredentials: true

168 },

169 beforeSend: function(xhr) {

170 xhr.setRequestHeader(backendCsrfHeaderName, backendCsrfToken); 171 }

172 })

173 // Function invoked in case the backend call was successful. 174 .done(function(data, textStatus, jqXHR) {

175 alert('success'); 176 })

177 // Function invoked in case the backend call failed. 178 .fail(function(jqXHR, textStatus, errorThrown) { 179 alert('failure');

180 });

4.3.3.3 Uploading the widget to the FIspace frontend (Wirecloud)

Log in to your account at the FIspace Experimental Environment. When the FIspace frontend is dis-played, on the left side of the screen, click on “Applications” as highlighted in Figure 14 below. This will lead to the dashboard, where the widget will be later deployed.

(27)

Figure 14: FIspace frontend after login - here you can find the link to your dashboard.

This dashboard is initially empty. Widgets are deployed from the local “marketplace”, which is also initially empty. So, as first step, we will upload a widget to this marketplace. To do so, click on the upload button that is highlighted in Figure 15.

Figure 15: The empty dashboard - here you can upload an application to your local "marketplace".

In the local marketplace, click the button that is highlighted in Figure 16 (the button text might be localised according to your browser’s language settings). A dialog window will pop up for selecting the widget, for instance “widget.wgt”. After selecting the widget file (from your local PC), press the button “Add”. This will upload the widget to the local marketplace and its “icon” will be displayed. Press on the button that is highlighted in Figure 17 in order to get back to the dashboard.

(28)

Figure 17: The widget in the local market place. The highlighted button leads back to the dashboard.

Pressing the “plus” button as indicated in Figure 18 will open a frame on the left side of the screen that shows the list of widgets available in the local marketplace. In our case, there is only one. Clicking on the “plus” symbol of a widget – as indicated in Figure 19 – will deploy the respective widget on the dash-board. The frame in which the widget is displayed can be resized by clicking and dragging its left lower corner.

Figure 18: Back on the dashboard. Here you can add widgets from the local marketplace.

Figure 19: Adding a widget to the dashboard.

4.3.3.4 Configuration of the widget

In section 4.3.3.1, the preference section of the file “config.xml” is described based on an excerpt from the downloadable FIspace widget example. The figures below show how to access the user-defined prefer-ences for a widget that has been deployed on the user’s dashboard (in the FIspace frontend, which is based on the Wirecloud GE).

When hovering the mouse pointer over the widget (more exactly, over its title bar), a set of symbols will appear (Figure 20). Clicking on the cogwheel symbol will open a menu – click on the menu item “Settings” (Figure 21). Finally, clicking on “Settings” will display a modal window (Figure 22) with those preferences

(29)

that had been defined in the file “config.xml” before. Here, the values of the properties can be changed as needed. At the next start of the FIspace frontend, the widget will read and use those values. In order to make the widget use the new values immediately, it needs to be reloaded, which can be done via the aforementioned menu by clicking “Reload”.

Figure 20: Hovering the mouse pointer over the widget's frame will reveal the widget menu.

Figure 21: Settings of the widget, which allows accessing the user-defined preferences.

Figure 22: The values of the widget’s preferences as defined in the file "config.xml" can be edited.

4.4 Step-by-step guide for business architects

Two complementary engines comprise the core modules in FIspace: the Business Collaboration Module (BCM) and the Event Processing Module (EPM). The BCM is responsible for orchestrating the different processes from different stakeholders and ensuring that the correct sequence of tasks are executed. The Event Processing Module (EPM) monitors events and detects situations of interest, i.e. situations that require appropriate actions. Together, both modules ensure that that all information and status updates

(30)

It is recommended to review the following slides to get an overview of the B2B component and the busi-ness architect guide for further details. There are also a Greenhouse sample and related materials avail-able to learn more about EPM and B2B working in practice.

4.4.1 Creation of a Business Process

Business architects can create business processes and templates via the FIspace frontend using the “Business & Capabilities” screen (Figure 23). A prerequisite for a business process is a business process template which also can be created on the same screen. Such a template can be created by providing a name and clicking on “Create”. Once created and after a refresh of the web page, a template is available for the creation of instances of it (i.e. business processes).

Figure 23: Create a Business Process Template

For creating an instance of an existing business process template the business architect have to choose a template from a list of already created ones (Figure 24) and add capabilities to be used within the busi-ness process by clicking on the plus symbol on the right (Figure 25). Capabilities were created by applica-tion developers for enabling business architects to choose appropriate funcapplica-tionality for the business pro-cesses. Within the capabilities an access point (i.e. address linking to the REST web service of an appli-cation backend which implements the capability) and types are defined. The capability type defines also the message type to be exchanged between platform and application.

(31)

Figure 24: Choose a Template for a Business Process

(32)

After the creation a business process can be edited in the ACSI editor (Figure 26) of the BCM module of the platform. The editor is accessible via the FIspace SDK, and also directly (fispaceUser / fispaceUser). In the ACSI editor the business entities as well as linked lifecycles, workflows and data access services can be edited. States and transitions can be created to change the workflow. Events and its effects can be refined and the external services can be defined. For a detailed description of the ACSI editor consult the manual.

Figure 26: ACSI Editor for Business Processes

For further information refer to FIspace business architect introduction the FIspace B2B documentation and the Guide for the BCM module.

(33)

A practical guide to app development for the FIspace Platform

Deliverable D600.1.1 & D600.1.2