A practical guide to develop an App for FIspace

FIspaceThis tutorial provides a practical guide to develop an App for FIspace. It represents a snapshot reflecting the current status of app development under FIspace.
The following sections give a first overview of the developer roles in FIspace (section 1) and of the architecture of a typical FIspace app as well as its connection to the FIspace Platform (section 2). This overview is followed by a step-by-step tutorial of How to develop a FIspace application (section 3), addressing both implementation and connection to FIspace, and by a step-by-step tutorial of How to configure a workflow in the FIspace Platform, that makes use of the functionality offered by other applications (section 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 categorized in business domains such as logistics or agriculture, and should provide reusable functionality within their business domain.
  2. Configurable collaborative workflows that make use of (subsets of) aforementioned capabilities, and also of external systems and services.
Figure 1: Extension mechanisms of the FIspace Platform.

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 applications 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 workflow 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 capabilities and thus constitutes the heart of a FIspace app.
  2. Business architect: Configures workflows on the FIspace platform that model the business processes 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.

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

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

Figure 2: Example for the typical architecture of a FIspace application and its connection with 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 Integration module. The backend also makes its business capabilities available to business processes via SDI.

 

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

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

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. product 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 between actors of the food supply chain in the course of a business process 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.

3. Step-by-step tutorial 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.

3.1 Preparation

3.1.1 Installation of development tools

For application development the Java Development Kit version 1.8 update 25 or higher and a development environment 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:

Optional/recommended resources and tools (functionality is also supported by several IDEs):

  • FIspace Studio/SDK, an online documentation describing the steps necessary to install the FIspace SDK and/or the FIspace Studio is available at https://bitbucket.org/fi-space/doc/wiki/sdk
  • Mercurial, a free, distributed source control management tool
  • TortoiseHG, a Windows shell extension and a series of applications for the Mercurial distributed 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

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. application developer and business architect) who have access to additional platform functionality (figure 5).

Figure 4: FIspace Home Screen

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.
    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 / componentized solutions and applications in form of FIspace applications.
    Application developers have access to security- and data integration-related functionality provided by the platform, like creating OAuth clients for applications and defining application capability types.
  • Business Architects: experts (internal or external to the User organization of the supply chain actor) that are in charge of configuring FIspace for their individual business needs.
    Business architects define customized collaborative workflows and connect those workflows with FIspace Applications and backend systems.

By default users of the FIspace platform do not have access to application developers- or business architects-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 FIspace-User-Mgmt@FIspace.eu. 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 registration)
  • 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

Figure 5: Functionality for FIspace Application Developers and Business Architects

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
Figure 6: FIspace BitBucket Core Repository

Figure 6: FIspace BitBucket Core Repository

With a fork you can work on a completely separate copy of the project without affecting any other developers. 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.

 

Figure 7: Fork of the FIspace Core Repository

Figure 7: Fork of the FIspace 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.

3.2 Creation of an application backend

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

Figure 8: Clone FIspace Core Repository using TortoiseHG

Figure 8: Clone FIspace Core Repository using TortoiseHG

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
  5. Press Clone

 

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 request (figure 10).
  4. As Reviewers add the following user names for informing the platform developers about your desired changes on the core repository:
    1. perezdf
    2. jhitado
    3. 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 accepted or rejected you will be informed via BitBucket.
Figure 9: BitBucket – User Repository

Figure 9: BitBucket – User Repository

Figure 10: Pull Request for Integration into Core Repository

Figure 10: Pull Request for Integration into Core Repository

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

Once new messages have been defined and committed to a copy of the FIspace core repository, a pull request has to be created for integrating the changes into the core repository (see end of section 3.2.1 for instructions). After the Pull request has been applied to the core repository changes are available for other developers and messages can be used for application development.

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 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 choosing an existing type or creating a new one. Users who want to create a capability need to provide:

Figure 11: Capability Creation

Figure 11: Capability Creation

  • 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

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

 

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

Figure 12: Creating OAuth Client

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

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:

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

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

Section 3.3.1 describes what a FIspace (application) widget is as well as its structure. Section 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 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 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.

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 Wirecloud GE) needs to be a widget. Such a widget is implemented in HTML5, CSS and JavaScript. Furthermore, 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 ZIPed (Using an archiving program such as Winzip, Winrar, 7zip or similar (compression method ZIP).), 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 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 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 3.2. The lower part allows exchanging data with aforementioned 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 selected 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 deployment. 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 declared 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.

 
 <!-- Platform.Preferences element. It defines user preferences -->
  <Platform.Preferences>
    <Preference name="backend_ip" type="text" description="Backend IP address" label="Backend IP" value="127.0.0.1" />
    <Preference name="backend_port" type="text" description="Backend port" label="Backend Port" value="8080" />
    <Preference name="backend_https" type="text" description="Use HTTPS for backend" label="Backend HTTPS" value="0" />
  </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.

Given an object MashupPlatform exists, the values of the defined preferences can be accessed by using 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. Besides preferences, there’s more information available in the Wirecloud instance (of the FIspace frontend). For instance, the user name of the currently logged in user – see in the listing below.

  
  function wirecloudGet() { 
    try {
      // Check if there is an instance of Wirecloud accessible by the widget.
      bWirecloud = false;
      if (typeof MashupPlatform !== 'undefined') {
        // If there is an instance, get the username of the currently logged in user. 
        backendUser = MashupPlatform.context.get('username'); 
        // Get the IP address, port number and HTTPS status of the backend from Wirecloud.
        backendIP = MashupPlatform.prefs.get('backend_ip');
        backendPort = MashupPlatform.prefs.get('backend_port');
        if (MashupPlatform.prefs.get('backend_https') === '0') {
          backendHTTPS = false;
        } else {
          backendHTTPS = true;
        }
        bWirecloud = true;
      } else {
        // At this point, no Wirecloud instance has been detected.
        bWirecloud = false;
        alert('Could not find a WireCloud instance!');
      }
    } catch(err) {
      alert('Encountered error(s) when reading the preferences from the Wirecloud instance!');
    }
  }
  

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 AJAX, which is also used for our sample FIspace widget. The (partial) listing below shows such a request to the backend. With $.ajax a POST request is send, while .done(function(data, textStatus, jqXHR) and .fail(function(jqXHR, textStatus, errorThrown) 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 Sharing, or short CORS, where the browser and/or the backend refuse to execute the XMLHttpRequest. For more information have a look at 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 the following statements take care of the CORS issue:


xhrFields: {
  withCredentials: true
},
beforeSend: function(xhr) {
  xhr.setRequestHeader(backendCsrfHeaderName, backendCsrfToken);
}

The full AJAX request:

 
    // Send the request to the backend (using jQuery AJAX).
    $.ajax({
      url: url,
      type: 'POST',
      data: JSON.stringify(obj),
      contentType: 'application/json',
      xhrFields: {
        withCredentials: true
      },
      beforeSend: function(xhr) {
        xhr.setRequestHeader(backendCsrfHeaderName, backendCsrfToken);
      } 
    })
    // Function invoked in case the backend call was successful.
    .done(function(data, textStatus, jqXHR) {
      alert('success');
    })
    // Function invoked in case the backend call failed.
    .fail(function(jqXHR, textStatus, errorThrown) {
      alert('failure');
    });
  

3.3.3 Uploading the widget to the FIspace frontend (Wirecloud)

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

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

Log in to your account at the FIspace Experimental Environment. When the FIspace frontend is displayed, on the left side of the screen, click on Applications as highlighted in figure 14. This will lead to the dashboard, where the widget will be later deployed.

 

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

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

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.

 

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.

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

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

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

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 dashboard. 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 18: Back on the dashboard. Here you can add widgets from the local marketplace.

Figure 19: Adding a widget to the dashboard.

Figure 19: Adding a widget to the dashboard.

3.3.4 Configuration of the widget

In section 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 preferences 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 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 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 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.

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

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 are provided to each involved stakeholder in real-time. Business architects use both modules to define customized collaborative workflows and connect those workflows with FIspace Apps and backend systems.

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

4.1 Creation of a Business Process

Figure 23: Create a Business Process Template

Figure 23: Create a Business Process Template

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

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 business process by clicking on the plus symbol on the right (figure 25). Capabilities were created by application developers for enabling business architects to choose appropriate functionality for the business processes. Within the capabilities an access point (i.e. address linking to the REST web service of an application backend which implements the capability) and types are defined. The capability type defines also the message type to be exchanged between platform and application.

Figure 24: Choose a Template for a Business Process

Figure 24: Choose a Template for a Business Process

Figure 25: Select Capabilities for a Business Process

Figure 25: Select Capabilities for a Business Process

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 (username: fispaceUser / password: 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

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.

Note

This tutorial is also as PDF in the download section available.