eeembedded d8.2 collaborative...

This project has received funding from the European Union Seventh Framework Programme

under grant agreement n° 609349.

OPTIMISED DESIGN METHODOLOGIES FOR ENERGY-EFFICIENT BUILDINGS INTEGRATED IN THE

NEIGHBOURHOOD ENERGY SYSTEMS

eeEmbedded – D8.2

Collaborative Methods

Responsible Authors:

Georg Dangl, Klaus Linhard, Peter Katranuschkov

Co-Authors:

Ken Baumgärtel, Eduard Mrazek, Romy Guruz

Due date: 31.12.2015

Issue date: 25.01.2015

Nature: Prototype

Coordinator: R. J. Scherer, Institute for Construction Informatics, Technische Universität Dresden, Germany

D8.2 Collaboration Methods

Version 1.0

/62

© eeEmbedded Consortium www.eeEmbedded.eu

Start date of project: 01.10.2013 Duration: 48 months

Organisation name of lead contractor for this deliverable: IAB

History

Version Description Lead Author Date

0.1 Document layout, structure and section “Underlying Technologies”

Peter Katranuschkov, CIB Klaus Linhard, IAB Georg Dangl, IAB

10.12.2015

0.2 Added introduction sections Georg Dangl, IABI 18.12.2015

0.3 Finished NEM input Eduard Mrazek, NEM 18.12.2015

0.4 Integrated NEM input with layout Georg Dangl, IABI 21.12.2015

0.5 Finalized IAB input Georg Dangl, IABI 21.12.2015

0.6 Finished CIB input Ken Baumgärtel, CIB 15.01.2016

0.7 Document discussion Romy Guruz, CIB Peter Katranuschkov, CIB Ken Baumgärtel, CIB Klaus Linhard, IAB Georg Dangl, IABI

15.01.2016

0.8 Layouting Georg Dangl, IAB 18.01.2016

0.9 Added bim+ Navigator section Eduard Mrazek, NEM 19.01.2016

1.0 Editing and finalization Georg Dangl, IABI Romy Guruz, CIB

22.01.2016

Copyright

This report is © eeEmbedded Consortium 2016. Its duplication is restricted to the personal use within

the consortium, the funding agency and the project reviewers. Its duplication is allowed in its integral

form only for anyone's personal use for the purposes of research or education.

Citation

Dangl, G., Linhard, K., Katranuschkov, P. (2016): eeEmbedded D8.2 Collaborative Methods © eeEmbedded Consortium, Brussels.

Acknowledgements

The work presented in this document has been conducted in the context of the seventh framework

programme of the European community project eeEmbedded (n° 609349). eeEmbedded is a 48

month project that started in October 2013 and is funded by the European Commission as well as by

the industrial partners. Their support is gratefully appreciated. The partners in the project are

Technische Universität Dresden (Germany), Fraunhofer-Gesellschaft zur Förderung der angewandten

Forschung E.V (Germany), NEMETSCHEK Slovensko, S.R.O. (Slovakia), Data Design System ASA

(Norway), RIB Information Technologies AG (Germany), Jotne EPM Technology AS (Norway),

Granlund OY (Finland), SOFISTIK HELLAS AE (Greece), Institute for applied Building Informatics IABI

(Germany), FR. SAUTER AG (Switzerland), , Obermeyer Planen + Beraten (Germany), Centro de

Estudios Materiales y Control de Obras S.A. (Spain), STRABAG AG (Austria) and Koninklijke BAM

Group NV (The Netherlands). This report owes to a collaborative effort of the above organizations.


Version 1.0

/62


Project of SEVENTH FRAMEWORK PROGRAMME OF THE EUROPEAN COMMUNITY

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)


Version 1.0

/62


Abbreviations

AEC Architecture, Engineering & Construction

API Application Protocol Interface

BF BIM Function

BIM Building Information Modelling

BPM Business Process Model

BPMN Business Process Model and Notation

CRUD Create, Read, Update and Delete

GIS Geographical Information System

HTML Hypertext Markup Language

Http Hyper Text Transfer Protocol

IDM Information Delivery Manual

IFC Industry Foundation Classes

JSON JavaScript Object Notation

KDP Key Design Parameters

KDR Key Design Requirements

KPI Key Performance Indicators

LOD Level Of Development

LoD Level of Detail

MVD Model View Definition

OData Open Data Protocol

REST Representational State Transfer

ScM Scenario Manager

SQL Structured Query Language

UML Unified Modeling Language

URI Uniform Resource Identifier

WFM Workflow Management

WMS Workflow Management System

WP Work Package

XML eXtensible Markup Language


Version 1.0

/62


Table of Contents

1 INTRODUCTION ......................................................................................................................... 7

2 UNDERLYING TECHNOLOGIES .............................................................................................. 8

2.1 REST APIs ................................................................................................................................................ 8

2.2 BCF ......................................................................................................................................................... 9

2.2.1 Structure ................................................................................................................................... 10

2.2.2 BCF XML Physical File ................................................................................................................ 12

2.2.3 BCF REST API ............................................................................................................................. 14

2.2.4 Exemplary Use Case of BCF ....................................................................................................... 14

3 COLLABORATION METHODS .............................................................................................. 17

3.1 General Concept................................................................................................................................... 18

3.2 BCF Driven Project Flow ....................................................................................................................... 19

3.3 BCF Querying ........................................................................................................................................ 20

3.4 Authentication, Responsibilities and Roles .......................................................................................... 23

4 IMPLEMENTATION ................................................................................................................ 24

4.1 Scenario Manager ................................................................................................................................ 24

4.1.1 Overview ................................................................................................................................... 24

4.1.2 Multi-Model Approach ............................................................................................................. 25

4.1.3 Ontology-based Process Support .............................................................................................. 27

4.1.4 User Interface and Underlying Technologies ............................................................................ 29

4.2 bim+ ..................................................................................................................................................... 31

4.2.1 Overview ................................................................................................................................... 31

4.2.2 bim+ API .................................................................................................................................... 31

4.2.3 bim+ Repository ........................................................................................................................ 32

4.2.4 Client API ................................................................................................................................... 36

4.2.5 bim+ Multi Model Navigator Application ................................................................................. 36

4.2.6 Implementations of the BIM Model API inside the bim+ repository ........................................ 38

4.2.7 Implementations of the BCF REST API - Client .......................................................................... 40

4.3 BIM--it .................................................................................................................................................. 46

4.3.1 Teams & Projects in BIM--it ...................................................................................................... 46

4.3.2 Managing Projects as BIM Manager ......................................................................................... 47

4.3.3 BIM Models ............................................................................................................................... 48

4.3.4 Collaboration View .................................................................................................................... 51

4.3.5 Project History and Timeline ..................................................................................................... 54

4.3.6 Architecture .............................................................................................................................. 54

4.3.7 Connecting with External Clients to BIM--it .............................................................................. 55

4.3.8 BCF Server ................................................................................................................................. 56

4.4 Model Servers ...................................................................................................................................... 57

5 CONCLUSIONS .......................................................................................................................... 58

6 REFERENCES ............................................................................................................................ 59


Version 1.0

/62


Executive Summary

The deliverable D8.2 – Collaboration Methods describes the results found in identifying and

implementing the workflows and technologies that were deemed necessary to create an

interoperable eeEmbedded platform. The BIM Collaboration Format and especially its Application

Protocol Interface that is used to exchange data between systems have been partially developed

during the course of D8.2.

Underlying technologies as well as the appropriate specifications that are used to enable a

collaborative workflow are described in this deliverable with examples picturing a real workflow that

show the benefit over existing technologies and methods as well as an outlook to what will be

available in the eeEmbedded testbed and later in the platform.

Processes and theoretical, non-technical concepts that are required for an effective data exchange

and teamwork scenarios are described. Additionally, technical implementations that support the

collaboration model and enable different services to be integrated with each other are described.

This includes services that were either developed anew for the eeEmbedded platform (e.g. BIM--it

from IABI) as well as already existing services that were adapted and integrated into the platform

(e.g. bim+ from NEM).

All partners have contributed to the R&D work. Contributions to the deliverable report are more

prominently from:

IAB - lead, overall structure, editing and layout, contributions to Chapters 1, 2, 3, 4.3 and 5

CIB - contributions to the report structure, Chapters 1, 3 and 4.1, final editing

NEM - contributions to Chapters and 4.2

D8.2 Collaboration Methods - Introduction

Version 1.0

/62


1 Introduction

This deliverable builds upon the Service Oriented Architecture (SOA) that was previously defined in

the eeEmbedded Deliverable D8.1 [1].

Figure 1 - Structure of the Service Oriented Architecture design in eeEmbedded [1, p. 10]

The present Deliverable D8.2 describes the technologies and methods used in the Communication

Layer of the architecture (see Figure 1). The Service Bus is consistently implemented via the BCF REST

API, whereas processes are controlled by having defined BCF structures for the eeEmbedded

platform. The applications that provide this functionality will be the Scenario Manager (section 4.1),

offering workflow management and control functionality, the bim+ Multi Model Navigator (section

4.2 for model and data visualization, and BIM--it (section 4.3), providing the communication layer

infrastructure and manual collaboration capabilities.

Figure 2 - Scenario Manager and bim+ Navigator connected via BCF over the BIM--it server

D8.2 Collaboration Methods - Underlying Technologies

Version 1.0

/62


2 Underlying Technologies

Deliverable D8.1 describes the platform architecture chosen for the eeEmbedded services. The

overview of the platform [1, p. 10f] shows that the three categories of components will be local apps,

web applications and services that provide the eeEmbedded platform infrastructure.

Essential for allowing effective collaboration to happen in a distributed environment is to use

common technologies with defined communication interfaces that enable the implementation of the

platform’s process and workflows. This Chapter focuses on the basic technologies chosen to support

the collaborative processes in eeEmbedded.

2.1 REST APIs

Representational State Transfer (REST) is a communication protocol architecture that is widely used

in the World Wide Web [2]. It offers an easy to understand, clearly specified set of rules that allow

the communication of different services.

On a basic level, a single call within a REST API has three main discriminators:

URI1: The location of the requested resource, such as the location of a model file

Verb: Declaration of the call intent, such as GET to retrieve data, POST to create new resources or DELETE to remove existing information

Payload: Depending on the operation, either the caller, the provider or both may send data along with a request, such as the data for a model upload or download

Regarding the content type used as payload, REST does not impose restrictions on the data format

being transferred. In contrast to binary protocols or alternative API approaches like SOAP2, this

allows for dynamic content negotiation between servers and consumers. For example, an object may

be either retrieved in JSON3 or Xml4 representation by sending a header to the server indicating the

desired content, in this case either Accept: application/json or Accept: application/xml. This

allows the use of whatever tools are most suited for the specific target environment. In creating

desktop software, there exists a huge environment surrounding Xml data, so clients intended to be

run as desktop applications might request Xml data where web applications might prefer their native

JSON data format. New data formats, such as MessagePack5 may be later introduced without

breaking existing implementations, since service providers and consumers dynamically negotiate the

contents format.

1 URI: Unique Resource Identifier, p.e. the Url to an article on a website or the path to a specific element in an

Xml file 2 SOAP: Simple Object Access Protocol, network API protocol for structured data exchange via web services

[14] 3 JSON: JavaScript Object Notation, the representation of objects in the JavaScript programming language, a

client side script language included in all modern browsers 4 Xml: eXtensible Markup Language, a human readable, verbose document description language

5 MessagePack: A data format similar to a binary


Version 1.0

/62


While REST has been in use for almost 20 years for Http6 data transfer [2], it is now becoming

increasingly popular as general application data communication protocol and is being chosen for

virtually any new API specifications. Due to the support in basically all frameworks and platforms

used for modern software development, it literally only takes minutes to get started with consuming

and providing services. The widespread use of REST APIs makes the integration of additional services

an easy task, since there is usually very little implementation overhead besides the actual API

integration.

Moreover, since it uses the same technology as the World Wide Web, security and authentication

can be based on tried and tested mechanisms. Frameworks and tools that support REST do usually

also support authentication and encryption mechanisms. For example, by requiring TLS7, it is possible

to inhibit transportation of non-encrypted data within the eeEmbedded platform.

2.2 BCF

The BIM Collaboration Format (BCF) was first developed in 2010 and has since gained ever increasing

popularity as an interoperable issue management technology that is supported by a multitude of AEC

applications. It arose from the need of having the possibility to have an open, vendor independent

data exchange format suitable for the diverse software infrastructure commonly used in the building

industry.

Since more and more projects adopted BIM centric workflows where IFCs8 interoperability could be

leveraged between partners from differing companies, it was becoming obvious that established

collaborative tools, often just simple issue tracking lists and non-specialized communication tools like

email, could not comply with the growing requirements for ever faster paced and complex

collaborative tasks. At first, BCF XML in version 1.0 was proposed by Tekla and Solibri [3], covering

both human readable data for issue management as well as integration to IFC model files with

references to model elements as well as visualization information. BCF has been proven to be a

success, since a lot of AEC design applications now have integrated or provide third party support for

the BIM Collaboration Format. After almost four years of use, buildingSMART9 released the second

version of the format in late 2014, thereby addressing found limitations within BCF.

As of version 2, there is now support to include schematized, arbitrary data along with BCF. These

attachments are called BIM Snippets and are a novelty to the modern collaboration process in the

AEC industry, since they allow content to be schematized and thus there is now the capability of

transporting information in predefined processes. For example, requests for a model change like

proposing an opening in a wall or specifying material properties had to be formulated via text and

could not easily be transferred between applications without a loss of information or potential

human error when doing a manual data entry. Today, first use cases and schemas are emerging in

6 Http: Hyper Text Transfer Protocol, specification for data communication in the World Wide Web

7 TLS: Transport Layer Security, the encryption of network traffic between client and server via public-private

key pairs. Commonly also called SSL, which is now mostly replaced by TLS 8 IFC: Industry Foundation Classes, a free, independent data format for building models

9 buildingSMART is a vendor independent organisation devoted to establishing common standards and

practices within the AEC industry. It’s operating worldwide and has regional chapters in most countries


Version 1.0

/62


the BCF Implementers Group10 and are made available in various software applications. The BIM

Snippet is one of the main features that makes the eeEmbedded workflow possible.

In 2015, buildingSMART released a REST based BCF API that makes the creation of location

indifferent, cloud hosted collaboration solutions possible. At the time of writing, first implement-

tations for both clients as well as servers have been developed and are already commercially

available.

The official specification of BCF is available at https://github.com/BuildingSMART/BCF-XML

2.2.1 Structure

The BIM Collaboration Format is using an internal structure to keep contexts of projects, users,

issues and attached information in a hierarchy. Figure 3 gives a brief overview of the composition

used within BCF.

Figure 3 - Structure of the BCF data format

Projects are the containers that act as root nodes in an AEC collaboration project. They are uniquely

identified, thus allowing easy integration and linking with project types in existing environments. It

can be envisioned as a separate, self-contained unit of work. For example, a single building project

like “Mall Downtown” would be considered a single project in BCF.

Extensions have been introduced with the second version of the BCF standard to allow a

customizable project setup. Where in the first release of the BIM Collaboration Format there were

only predefined values for domains or states11, project extensions now allow the definition of

arbitrary values for certain concepts like domains used in a project, available topic states (like Open,

Closed and Reopened). The list of users is also given in the extensions, providing information about

valid user names of participants in the project. Note, however, that no user rights management is

contained in BCF. This is left to actual implementations which are often covering more than just the

BIM Collaboration Format and have their own management options.

10

BCF Implementers Group: Interested companies and software vendors that are committed to implementing BCF and offering commercial collaboration solutions to the AEC industry

11 Some implementations did support custom project settings, but there was no support to sync these

between different applications.

Project

Topic

Comments

Viewpoints

Topic

Extensions

Users

Settings


Version 1.0

/62


Topic is the unit representing a single issue in BCF. It transports communication data such as text and

comments and offers elements to discuss and track issues. Relations to other topics are possible, for

example multiple detected clashes might be aggregated and solved with a single voiding element. As

will be shown in section 2.2.4 “Exemplary Use Case of BCF”, visualization information like camera

positioning and screenshots are part of a topic and are used to relate model information in tools

capable of displaying and / or altering models. To further detail an issue, specific information of the

model12 is transported along a Viewpoint, making highlighting of problems less error prone. Issue

and assignment management is possible via a historical status tracking and specifying responsible

persons, with many implementations even offering sophisticated functionality to set up rights and

view tamper proof change data on topics, making BCF ideal to work on issues that imply legal

obligations, such as design errors.

Finally, with the attachments called BIM Snippets, schematized data may be sent to support virtually

any exchange scenarios relying on specified data. A proposal for a schema to integrate facility

management software needs to keep track of and change element properties has been made by

Thomas Liebich [4], where the content of a snippet would be schematized using a Model View

Definition (MVD)13.

In the following example, the exchange of a property set update is requested. The format for this

exchange is a partial ifcXML file, which is the Xml representation of IFC. Line 03 is referencing an

IfcWall entity via its IfcGuid identifier. The Xml element itself defines that a property called

“FireRating” should be attached with a value of “W-90” to the referenced IfcWall.

01: <?xml version="1.0" encoding="UTF-8"?> 02: <ifcXML xmlns="http://www.buildingsmart-tech.org/ifcXML/IFC4/final"> 03: <IfcProduct GlobalId="1q8kSixn57xRqAocWhCd5K"> 04: <IsDefinedBy> 05: <IfcRelDefinesByProperties> 06: <RelatingPropertyDefinition> 07: <IfcPropertySet Name="Pset_WallCommon"> 08: <OwnerHistory ChangeAction="modified"> 09: <OwningUser> 10: <TheOrganization Name="Fire Consulting Co"/> 11: </OwningUser> 12: </OwnerHistory> 13: <HasProperties> 14: <IfcPropertySingleValue Name="FireRating"> 15: <NominalValue> 16: <IfcLabel-wrapper>W-90</IfcLabel-wrapper> 17: </NominalValue> 18: </IfcPropertySingleValue> 19: </HasProperties> 20: </IfcPropertySet> 21: </RelatingPropertyDefinition> 22: </IfcRelDefinesByProperties> 23: </IsDefinedBy> 24: </IfcProduct> 25: </ifcXML>

Table 1 - BIM Snippet content that transports element property set data (simplified) [4]

12

IfcEntities deriving from IfcRoot may be selected within a topic’s viewpoint

13 MVD: Model View Definitions are used to define rules that a model must comply to, i.e. defining required

content in an IFC model file via a mvdXML schema


Version 1.0

/62


2.2.2 BCF XML Physical File

The Xml based physical file format of BCF is a zip14 archive that contains a hierarchical structure of

single files. It is associated with the file extension “.bcfzip”. At the uppermost level, the project- and

BCF metadata is defined (see Figure 4). It may contain the following three files:

project.bcfp – Container for referencing a certain IfcProject. This is used to create links between BCF files and building projects in other systems

extensions.xsd – This file contains project settings that are used to configure the project (see section 2.2.1)

bcf.version – A file with predefined content, identifying the version of the BCF container to allow processing applications to extract the version without having to parse the file content itself

Figure 4 - BCF XML Content - Top Level

For each topic that is present in a BCF file, there is a folder at the root level named with the GUID15 of

the topic. The topic folder contains data about an actual issue, an example is shown in Figure 5

below.

Not shown here is the capability to include various attachments. The BIM Snippet has already been

described in section 2.2.1, but there is also the possibility to store (and reference) documents of any

type within the BIM Collaboration Format. Additionally, the BCF specification states that applications

should preserve files contained in a container and pass them on when changes are being saved and

exported. This allows arbitrary data storage and transport.

14

Zip: An archive file format that stores folder hierarchies in a single file and compresses them to save space [15]

15 GUID: Globally Unique Identifier, 128-bit / 32-byte sequence that is reliably unique when generated with

correct implementation algorithms. It can be used to generate non duplicate identifiers across different, non-connected systems with virtually no risk of collisions in the generated data


Version 1.0

/62


Figure 5 shows the content of a folder storing a single BCF issue. The most used components are:

markup.bcf: This is an Xml file that contains the data object representing a BCF topic. Table 2

shows a sample content of such a file.

Viewpoint.bcfv: Here, geometric information such as camera positioning and model

references like IfcComponents are referenced to establish a link between a topic and a

building model. Table 3 shows a sample content of such a file.

Snapshot: These are image files that may be attached to a viewpoint. They can serve as a

preview to an issue or to visualize viewpoints in systems that do not have model rendering

capabilities

snippet (not shown): If a topic contains a BIM Snippet, it is possible to include it within the

topics folder. Snippets can also be given as references that might point to a web address or a

shared BIM Snippet in the BCF XMLs file root directory

Figure 5 - BCF XML Content - Topic Folder

01: <?xml version="1.0" encoding="utf-8"?> 02: <Markup xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 03: <Topic Guid="6a4f8cf5-55c0-45e9-b8d7-d7e7493d60bb" TopicType="Info" TopicStatus="Open"> 04 <Title>Ensure Load Bearing Capabilities for Solar Panels on Roof</Title> 05: <Priority>Medium</Priority> 06: <Index>0</Index> 07: <Labels>Architecture</Labels> 08: <Labels>Structural</Labels> 09: <CreationDate>2015-12-10T17:56:38</CreationDate> 10: <CreationAuthor>[email protected]</CreationAuthor> 11: <AssignedTo>[email protected]</AssignedTo> 12: <Description>Please make sure that the roofs structural requirements take possible future 13: solar panels into consideration.</Description> 14: </Topic> 15: <Viewpoints Guid="df0f0a72-f446-4833-b138-c1ac17fb7cf5"> 16: <Viewpoint>Viewpoint_df0f0a72-f446-4833-b138-c1ac17fb7cf5.bcfv</Viewpoint> 17: <Snapshot>Snapshot_df0f0a72-f446-4833-b138-c1ac17fb7cf5.png</Snapshot> 18: </Viewpoints> 19: </Markup>

Table 2 - Xml Content of a BCF XML Topic Entry (simplified)


Version 1.0

/62


Table 2 shows the Xml content of a single topics markup.bcf file. It contains the text based

collaboration information on lines 03 throughout 14 and additionally creates a reference to a

viewpoint and its associated snapshot on lines 15 to 18.

01: <?xml version="1.0" encoding="utf-8"?> 02: <VisualizationInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 03: <Components> 04: <Component IfcGuid="2Nv5yGyGD3KBz3s3UUmiry" Selected="true" /> 05: </Components> 06: <PerspectiveCamera> 07: <CameraViewPoint> 08: <X>25.1832013761057</X> 09: <Y>-9.79458498614105</Y> 10: <Z>21.5905751812886</Z> 11: </CameraViewPoint> 12: <CameraDirection> 13: <X>-0.469668531519944</X> 14: <Y>0.6506162391203</Y> 15: <Z>-0.596749524901043</Z> 16: </CameraDirection> 17: <CameraUpVector> 18: <X>-1.1889053198282888</X> 19: <Y>0.056710342544771</Y> 20: <Z>0.997551000253279</Z> 21: </CameraUpVector> 22: <FieldOfView>60</FieldOfView> 23: </PerspectiveCamera> 24: </VisualizationInfo>

Table 3 - Xml Content of a BCF XML Viewpoint

The BCF Viewpoint shown as example in Table 3 contains information about the positioning of the

camera (lines 06 through 23). Additionally, a single component, identified by its IfcGuid from the

original model file, is marked as being selected (line 04). This would make an application that

visualizes this viewpoint assume the given camera position and highlight the component, which in

this example topic is the roof of the building.

2.2.3 BCF REST API

Accompanying the specification of the second generation of the BCF XML data format, a

buildingSMART initiative led by iabi was started to create an open, publicly available BCF API that

could make the file based collaboration ready to be used as a cloud based communications

technology. Since its initial release in late 2014 and subsequent approval as official standard by

buildingSMART in spring 2015, first implementations have been created that support it.

The BCF API is specified as a REST API that has features identical to the XML based BCF file format,

allowing a complete integration into any clients or servers that support the BIM Collaboration

Format. The official BCF API specification is available at https://github.com/BuildingSMART/BCF-API

2.2.4 Exemplary Use Case of BCF

To get a better understanding of what is possible with BCF, let us look at an imagined workflow. The

project has already advanced for a while and is currently in the detailed design phase, where a lot of

the modelling decisions have already been made. Alice the architect is using BIM--it, the collabo-

rative web application and BCF server developed by iabi, to check the latest revision of the model for

any open issues that may have been overlooked so far.

https://github.com/BuildingSMART/BCF-API


Version 1.0

/62


She finds out that, while inspecting the roof, the owner’s request to take the possibility of future

solar panels on the roof into account have not yet been communicated to the structural engineer.

The appropriate IfcPropertySet, which would define a load bearing class for solar panels, is not

present on the roof of the building.

Figure 6 - The highlighted building roof in BIM—it

Alice marks the component in the viewer tool and creates an issue that references the model (see

Figure 6 and Figure 7).

Figure 7 - Creation of a BCF Topic in BIM--it

Bob is responsible within the project for the structural modelling of the building. Depending on the

tools used, there are different ways Bob might be made aware of the issue. If his native modelling

tools support the BCF API, he might be notified immediately about new issues. He could also be

notified when using the collaboration platform, or even just be sent the BCF file via email from Alice.

Since BCF is supported by different applications, it is up to Bob to choose which environment to work

in (See Figure 8 and Figure 9 as examples).


Version 1.0

/62


Figure 8 - The issue opened in BCFier16

Figure 9 - The issue imported in Solibri Model Checker

If the raised issue is opened with the native modelling tool of Bob, it is possible for him to quickly

take care of the problem and then comment on the BCF topic that the missing property has been

taken care of. Alice, as the owner of the issue, can verify it by simply reopening the topic herself and

checking if the load bearing category is now present. If it is, she may mark the topic as finished. It will

no longer be listed as requiring action, but the history is available for whenever the steps taken must

be looked at again.

16

BCFier: An open source, free tool that supports BCF version 2. Website: http://bcfier.com

D8.2 Collaboration Methods - Collaboration Methods

Version 1.0

/62


3 Collaboration Methods

Figure 1 on page 7 shows the overview of the general architecture of the eeEmbedded platform.

Regarding the Service Bus and the collaboration methods, there is the need to specify the methods

and conventions that are being used in the project to enable the seamless integration of different

tools within the architecture.

Workflows in the collaboration process are defined in Deliverable D8.1 [1, p. 22ff] “Scenario Work-

flows”.

For an effective collaborative process, two prerequisites must be fulfilled:

1. Workflows, capable of modelling the user expectation as well as the business rules required

for a certain task, must be designed and agreed upon by the individual collaborators. This can

be done in an ad-hoc schema, as typically done in current construction projects where for

example a responsible project manager defines action steps to be taken on per-need basis.

More sophisticated systems already provide functionalities to define, enforce and reuse

processes modelled in their respective environments. Ideally, workflows that are not specific

to a single project are defined in advance, such as via industry standards, are universally seen

as correct and beneficial and do not conflict with or complicate the work done by individual

experts.

The latter approach is what is being done in eeEmbedded. Earlier deliverables, especially D8.1

[1], have already identified major tasks and their structure. This deliverable will describe how

they can be translated into application-interoperable definitions.

2. Adequate technologies and tools must be available to support the workflow by offering

guidance through the process and taking care of tasks that the user does not need to worry

about. This is still a big obstacle in modern design teams that span multiple offices, since

there are hardly (if any) approaches available that support process synchronization between

applications.

This lack of tools manifests in teams falling back to the least common denominator, which is

usually manual process supervision by responsible managers. Connections between models

(geometric, energy, cost), project state (such as timetables and milestones) and individual

duties are hardly centrally available. Seamless integration is not possible with most systems,

leading to error prone tracking of information via spreadsheets and often incur a loss of

information when information is exchanged between systems.

Therefore, this deliverable describes how the collaborative workflows can be modelled and how the

technologies developed are used for the implementation. Use case scenarios, that are modelled as

sequence diagrams in D8.1 are used as example for demonstration. The goal is to have collaboration

methods clearly defined and relying on open technologies, so that services in the platform are easily

interchangeable.


Version 1.0

/62


3.1 General Concept

While analyzing methods that can be used in a BIM based collaboration processes, it was discovered

that tasks, which can also be called BIM functions, can be categorized in three main groups with a

total of five distinct sub groups that have certain characteristics.

Three main categories represent the assignment of basic roles in a workflow process.

Tasks that are categorized as Performance do lead to new data being created. They contain two

subtypes, where Design includes the creation process of an actual model, i.e. an architectural IFC file,

executed by a designer. Service functions provide data extraction or enrichment based on an existing

model, for example the composition of a bill of quantity or the performing of an energy simulation.

This is done by consultants or domain experts.

Functions categorized with Assessment revise tasks, validate models and data and propose solutions

on identified errors. This is the typical role of project management and might include jobs like

ensuring that created models comply with project requirements such as energy consumption or

schedules. It is differentiated from the BIM Manager role in that assessment functions require an

expert domain knowledge and do not control the general workflow.

Workflow control is covered by the Control subtype of the Decision category, which is performed by

the BIM Manager. Lastly, decisions makers such as owners are responsible to perform or delegate

tasks concerned with judgment of inputs. [5]

Performance Assessment Decision

Design BF17

Service BF Assessment BF Control BF Choice BF

Designer Consultant Project Manager BIM Manager Owner Status

Status

Status

Status

Status

Open

Open

Open

Open

Open

Suspended

Suspended

Suspended

Suspended

In Progress

In Progress

In Progress

In Progress

In Progress

Overdue

Overdue

Overdue

Deployed

Reviewed

Reviewed

Completed

Completed

Completed

Completed

Completed

Table 4 - Types of BIM functions (modified) [5, p. 33]

As described in section 2.2.1, BCF topics contain properties that can be customized and used for

project defined requirements.

17

BF: BIM Function, an atomic task in a BIM workflow [5]


Version 1.0

/62


3.2 BCF Driven Project Flow

The Business Process Model and Notation (BPMN) is a graphical representation for specifying

processes. [6] It is an international standard, maintained by the Object Management Group

(http://www.omg.org) and is widely used as a technology to describe processes with a great number

of tools available. It is very similar to the Unified Modelling Language (UML) used to represent the

structure and flow of object oriented programs. Describing tasks that have a lot of validations and

different execution paths are naturally easy to represent and understand in BPMN. The basic

concepts are intuitive and do not require formal training.

As an example, see the following process described in BPMN (Figure 10).

Figure 10 - Basic example of a process modelled in BPMN

The figure describes the process of “Model Creation”. The diagram is partitioned in two lanes, each

one representing the workspace of a single actor, “Architect” and “BIM Manager” in this case.

Creation of a model is the responsibility of the Architect, who relies on prerequisites being provided

in advance. There are two decisions gateways shown, one deciding whether or not the input needed

in order to create the model is present and correct and the other one having the BIM Manager

decide after the publication of a model if it passes a check. Depending on the outcomes of the

decisions, the course of actions might change to take appropriate, predefined steps. It defines only a

single start and end, meaning the process is intended to have a single defined outcome (the creation

of a model) and the internal actions are set up in a way to ensure this result will eventually be

reached.

The BPMN as-is might be a good description of the actions that are involved when creating a model.

It also does indicate that there is collaboration between the Architect and the BIM Manager, but the

exact nature of the collaboration is open. It would be up to whoever creates a platform supporting

this process creates the required communication channels to allow for collaboration, but this is not a

convenient way to describe collaboration interfaces.

The eeEmbedded platform specification will utilize custom data annotations to support the definition

of API specifications to allow the description of detailed collaboration process information. The

process diagram from Figure 10 is shown below with additional details added.


Version 1.0

/62


Figure 11 - Enriched process diagram with attached collaboration information

An example of a connection to a repository service is given for the action “Upload to Repository”,

where an artefact “Model Repository” is attached to indicate that the action requires interfacing with

a BIM Model API service to store the created model in eeEmbedded’s platform infrastructure.

Furthermore, actions that require collaboration between actors are marked with the BCF icon. This is

typically happening whenever the process switches lanes, i.e. when the user currently executing is

changing. For example, when the “Input Data Complete” gateway resolves to “No”, the Architect

performs the “Create Issue” action. This does trigger the creation of a BCF topic that contains the

details of what caused the precondition to fail. Subsequently, the BIM Manager gets involved by

receiving the topic and starts his task “Gather Prerequisites”, i.e. by specifying unambiguous

instructions for the Architect.

3.3 BCF Querying

Due to the nature of REST APIs, they are less integrated in systems and therefore might suffer

performance drawbacks when no appropriate endpoint resources are provided. This can cause

problems when the API does not know about the intent of the consumer. To give an example, let’s

image a client for BIM Managers in the eeEmbedded platform. The user does want to get notified

about occurring issues; such as an Architect being delayed in his work due to missing input data (cf.

Figure 11). Such notifications are not categorically distinguishable from any other topics that may be

created in a project. To counter this, the BCF API specifies that all collection resources, i.e. resources

that return more than a single object, do implement the OData18 filtering protocol to let clients

specify custom data queries when accessing collections. Consider this example:

In a given project, the following result set is returned when querying the topics of a project via

GET https://bim--it.net/bcf/1.0/Projects/8EEE1572-E379-4DEC-96E7-808CBD4996C2/Topics.

18

OData: Open Data Protocol is a protocol specification on top of REST APIs that describes methods to query datasets and only have matching results returned. It can be integrated into systems to translate REST API queries to native data models, meaning performant sorting and filtering technologies may be used. [17]

https://bim--it.net/bcf/1.0/Projects/8EEE1572-E379-4DEC-96E7-808CBD4996C2/Topics


Version 1.0

/62


[

{

"guid": "a32d6a9b-12d0-48f7-afec-93395cc4153b",

"title": "Next Project Steps",

"creation_date": "2015-12-17T15:05:42",

"creation_author": "[email protected]",

"topic_type": "Info",

"topic_status": "Open",

"priority": "Medium",

"assigned_to": "[email protected]",

"description": "Please coordinate the next project steps."

},

{

"guid": "ebe4adeb-cd7f-483d-be73-251f9d5dc984",

"title": "Issue: Missing Specifications",

"creation_date": "2015-12-17T15:07:13",


"topic_type": "eeE - BIM Manager Issue",


"priority": "High",

"labels": [

"Architectural"

],


"description": "Specifications for the architectural model are missing."

}

]

Table 5 - Unfiltered BCF API topics response

The client would only need to react to the second topic, since this has the “topic_type” property set

to “eeE - BIM Manager Issue”, utilizing a predefined value in the eeEmbedded platform specification

to raise automated client actions. However, when implementing a scheduled polling of the BCF

server for events, it’s not feasible to query the whole list of topics each time. In actual projects, it’s

not unlikely that there are thousands of topics, straining bandwidth and general performance as a

result.

To counter this, the client only needs to keep track of when the last raised issue was created or

modified and then use OData for subsequent API calls. The request would look like this:

https://bim--it.net/bcf/1.0/Projects/8EEE1572-E379-4DEC-96E7-808CBD4996C2/Topics

?$filter=creation_date gt 2015-12-17T15:07:13Z or modified_date gt 2015-12-17T15:07:13Z

The latter part of the request contains a ?$filter Uri parameter that defines two expressions. The

first one tells the server to only return topics whose creation_date has a value greater than (gt)

2015-12-17T15:07:13Z (Z indicates the universal / Greenwich time zone UTC, decoupling it from

time zone localization issues). The second part of the search term is a logical or condition, meaning

topics that were modified since the last update should also be included.

See Table 6 and Table 7 for the effect this filter has on the returned collection.


Version 1.0

/62


[

{

"guid": "a32d6a9b-12d0-48f7-afec-93395cc4153b",

"title": "Next Project Steps",

"creation_date": "2015-12-17T15:05:42",


"topic_type": "Info",


"priority": "Medium",


"description": "Please coordinate the next project steps."

},

{

"guid": "ebe4adeb-cd7f-483d-be73-251f9d5dc984",

"title": "Issue: Missing Specifications",

"creation_date": "2015-12-17T15:07:13",




"priority": "High",

"labels": [

"Architectural"

],


"description": "Specifications for the architectural model are missing."

},

{

"guid": "55098de8-97a5-47a7-a547-41df1eb8f5ff",

"title": "Issue: Ambiguous Specifications",

"creation_date": "2015-12-17T16:12:55",




"priority": "High",

"assigned_to": "[email protected]"

}

]

Table 6 - BCF topic resource response after an additional issue was created

When the query is sent again with the applied filter, the output changes to only include the new topic.

Again, the client would store this topics creation data and use that for subsequent calls to the server.

[

{

"guid": "55098de8-97a5-47a7-a547-41df1eb8f5ff",

"title": "Issue: Ambiguous Specifications",

"creation_date": "2015-12-17T16:12:55",




"priority": "High",

"assigned_to": "[email protected]"

}

]

Table 7 - BCF topic resource response with the applied filter


Version 1.0

/62


The BCF API offers more sophisticated filter options to give clients maximum flexibility when

performing queries. On a basic level, most expressions found in SQL19 are present, allowing queries

to define ordering, skip records or perform nested expressions. Advanced functions allow predefined

methods such as string-, GIS20- or mathematical operations to be performed on the data.

3.4 Authentication, Responsibilities and Roles

Projects and processes that involving multiple users do require means to authenticate users and

management of permissions, which are often done via role based permission settings.

Software implementers have discussed how to handle a globalized user authentication and

authorization mechanism for the eeEmbedded project. It was since decided that this will not be part

of the initial prototype implementations that are used for creating the testbed since a centralized

user management involves deep integration in existing vendor systems. Additionally, it does not

seem necessary to have a dedicated user server for the eeEmbedded platform when there are

already a lot of global authentication providers available. For example, Microsoft- and Google

accounts may be used to authenticate with different services. The eeEmbedded platform would then

only have to keep track of user permissions, but since this is a non-repetitive task that is usually only

performed when a new user is introduced to a project, it is deemed feasible to not have a dedicated

platform functionality available for that but instead to rely on the individual systems

implementations.

19

SQL: Structured Query Language, a standardize language that is used mostly in relational database systems to access and manipulate stored data.

20 GIS: Geographic Information System, a computer program that handles spatial or geographical information

such as terrain data, elevation levels or infrastructure inventory.

D8.2 Collaboration Methods - Implementation

Version 1.0

/62


4 Implementation

4.1 Scenario Manager

4.1.1 Overview

The overall collaboration of multiple users and their workflows is based on BCF for exchanging

messages and on BIM servers for managing BIM data with a desktop tool, called Scenario Manager

(ScM). In the ScM a BIM manager can define the global construction process based on Information

Delivery Manual (IDM) and Business Process Models (BPMs) via BPMN. This process is shared by the

ScM and the current status in the eeEmbedded design workflow is shown to all participants. There

are various use cases where the ScM can be applied to ease the collaboration between different

participants whether the users are directly or indirectly involved in the building construction process.

Figure 12 shows such use cases which can be covered by the ScM. All possible domains and

participants within the BIM process can benefit by using this tool.

Figure 12 - ScenarioManager use cases

By addressing these use cases and the changed way of working in the concept and design phase of a

construction project, there is a need to integrate multiple domain models into such a BIM collabo-

ration platform based on the two standards, IDM/MVD and BCF. These established methodologies

and techniques have to be advanced so they can also be used as basis of a distributed multi-model

BIM collaboration platform.

Figure 13 presents the general usage of the ScM together with a BCF Server. All models expressed as data

files can be dropped in the workspace of the ScM and will be shared to other participants via BCF


Version 1.0

/62


messages. Every time a new message is sent to a user s/he will be informed about changes and will get

the latest data which is needed to fulfil the task of the user. The shared data can be input for and output

data of other tasks. For example, the simulation input and Key Performance Indicators TO-BE can be

transferred to the energy planner [7], while the simulation results can be provided to the decision maker.

Figure 13 - Application of ScM together with a BCF Server

4.1.2 Multi-Model Approach

For the combination of different heterogeneous domain models we are using the multimodel approach

which was developed in the German Mefisto project [8] to use existing data models (called elementary

models) as they are and create an exchange format which defines loosely-coupled links between the

domain models. This approach specifies meta data with information about the elementary models and

one or more link models (LM) where all relations between multiple elementary models are stored. Each

LM can be seen as one variant of a knowledge space, e.g. a design variant. All domain models and the

link models are packed in a multi-model container (MMC) and can be shared between software

applications (see Figure 14).

The advantage is that the applications only have to analyse the LM which is a simple XML file and

that all domain models are kept in their origin data format like IFC. The other advantage is that the

information from domain models is always up-to-date but the disadvantage is that the LM must be

kept valid against the domain model content, for example if identifiers are changing due to changed

geometry (e.g. split of walls).

Regarding the usage of BCF in a multimodel based data management a BimSnippet addresses one specific

data model (mostly IFC). To use BCF for multimodels the fixed cardinality should be increased so that BCF

itself can be used as container for all relevant models of multi-model. But this change can affect software

products already using BCF. A MMC encapsulates the necessary data models and link models using XML

based description and the concept to provide data models as raw format or to address data models via


Version 1.0

/62


Uniform Resource Identifier (URI) [8]. Instead addressing all necessary data models of a multimodel, MMC

makes it possible to use only one address and fits perfectly to the BCF concept.

Figure 14 - Multimodel approach with multiple domain models and link models connecting these elementary models

The Process Map is modelled as Pool including the actors as Swim Lanes. The Swim Lanes contain the

activities assigned to the actors connected by message flows (see Figure 15). The building

information model is modelled as Swim Lane and the defined Exchange Requirement (ER) is

connected as message event related by an information document about the building information

model to the exchange point. This notation can be extended to cover the multimodel approach by

splitting one common information model into elementary models and link models.

Figure 15 - Output of Process Map based on a) conventional single model (e.g. IFC), b) multimodel approach and c) process-centric multimodel approach


Version 1.0

/62


Figure 15 shows that the IDM/MVD methodology produces a lot of documents that can be used as

basis of a contractual collaboration but not as structured data for software interoperability. Regarding

technical interoperability IDM/MVD only provides the computer-readable XML based format mvdXML

that has to be laboriously created by entering the MVDs in the ifcDoc tool [9] and it only works for the

IFC data schema. However, as far as MVDs are used as document, there should be no problem to use

this document structure to describe also the exchanged data of non-IFC data schemas.

4.1.3 Ontology-based Process Support

Figure 16 below shows the extension of the single model-based BCF by using the MMC to allow the

usage of multiple domain models for defining large information spaces with BIM and non-BIM data

to enable energy performance analyses. The Multimodel View Definitions (MMVDs) are hereby

combinations of model-specific MVDs to define data requirements within the information space. This

is enabled by the use of ontologies which will be implemented in WP 5.

Figure 16 - Single model BCF collaboration (left hand) and knowledge-based multi-model collaboration (right hand)

The elaborated process of IDM/MVD methodology with its activities and their flows, even modelled

in the standardized BPMN format, as well as the link information of an activity to their consumed and

produced data and its assigned actor or executing service are only used as process documentation

until now. This information is available and can be easily integrated in multi-model content

management by storing the process model and user model in a content management system using

an ontology to link the activities to data models and actors (see Figure 17) [10]. This process-centric

data management can be used as basis of the process-driven Scenario Manager by integrating a

workflow management system (WMS) handling primarily the data flow (arrows from Tool A to

Workflow Management (WFM) Engine and from WFM Engine to Tool B). Considering the rising

amount and complexity of the data during early phases of a construction project, software solutions

are needed to support the collaborators as well as the decision-maker and BIM manager in handling


Version 1.0

/62


the data during the collaboration process in the sense of automatic data validation, data linkage,

data filtering and data transfer/transport.

Figure 17 - Workflow-driven multi-model BIM Scenario Manager

Thereby the requirement models introduced in [11] can play a major role. The requirement model

specifies the requirements on a specific task e.g. the design of a building that an architect has to

create or the resulting values of simulation that an engineer has to deliver and how they can be

verified to guarantee data quality. These task requirements are also assigned to a task and could also

be integrated in the ontology based content management system and be linked with tasks (see

Figure 17) [10].

The Workflow Management Coalition developed a Workflow Reference Model that describes the

components and interfaces of a common WMS [12]. The core component is the WFM that provides

the runtime environment for a workflow instance. During execution of a workflow instance the

engine consumes and produces different data that is provided by the Workflow Enactment System.

Figure 17 illustrates that these data can be also provided by the described multi-model content.

Figure 18 below shows the UML sequence diagram of a common use case describing two interacting

participants. The participants are using the ScM including the functionality of a multi-model client

and a workflow engine. The workflow execution begins by editing the start task. After completing his

task, the workflow participant releases his work results for the next participants in the workflow. A

release leads to automatic validation of the results. When the validation fails the work results cannot

be released and the user gets some information why his/her work is not sufficient and what s/he has

to rework. When the validation succeeds the work results are encapsulated and delivered to the next

participants in the workflow who is known because of the underlying process model and the linkage

of the activities to participants. The successor receives the BCF and begins his/her task. Based on the

validation, there should be no complications in terms of data quality, but still the receiver should also


Version 1.0

/62


be given the opportunity to reject the received work results. In case of a rejection, a BCF message is

sent with the appropriate comment and possibly even the same data back to the sender of the BCF.

This can go back and forth, in which case BCF is more used as a comment. We have identified a set of

topics used to execute the workflow in an automatic way. These are “Task released” and “Task

rejected” during execution and “New Task” and “New Task rejected” during set up. After receiving a

new task in the set-up phase, it can be accepted or rejected by the workflow participant. In case of

rejecting, the decision maker is notified and changes the entire workflow and distributes it again to

all participants or a single activity is changed and distributed to one specific participant. In case of

accepting the tasks, no further notification to decision maker is necessary. If all tasks are accepted

the workflow can be executed.

Figure 18 - Excerpt of an UML sequence diagram of the workflow execution

4.1.4 User Interface and Underlying Technologies

Figure 19 presents an excerpt of the GUI of the ScM BIM project perspective with several views. This

perspective can be seen by the BIM manager who creates the overall project workflow. On the left-

hand side is the Project Explorer where all BIM projects of the participants are shown with their

current data. The BPM is also stored and shows the current state of the project workflow. On the

right-hand side the BIM manager can create or update the BPMN of the process by adding new tasks

or ERs to the tasks. On the bottom the BIM manager can assign project workers to the tasks and can

specify due dates of tasks so that an overall time plan can be specified. The BPMN is stored as XML

file and can be interpreted by the workflow engine of the ScM which is based on the Activiti

framework [13].


Version 1.0

/62


Figure 19 - ScenarioManager GUI, left side: Project Explorer, right side: Project Settings Palette for defining BPMs, bottom: Properties to manage activities in processes

The BCF message view is shown in Figure 20. Each message is structured like an email with a title,

description and attachments transferred through an MMC. Additionally, the current process state is

shown so that the user has a fast overview in the global process. Such a message can be accepted if

the content is sufficient for his/her work or declined if there are problems. Each message can contain

requirements and resources for the next task.

Figure 20 - BCF message view in ScenarioManager

The ScM implementation is based on Java with popular business frameworks like Spring

(https://spring.io), Hibernate (http://hibernate.org), SWT (https://www.eclipse.org/swt), the

semantic web framework Jena (https://jena.apache.org), the workflow management framework

Activiti (http://activity.org) [13], and the REST support framework Jersey (https://jersey.java.net).


Version 1.0

/62


4.2 bim+

4.2.1 Overview

bim+ is an open, “All-Connect” platform for connecting people, information and BIM models to build

faster. bim+ is Open BIM compliant. It provides universal access, sharing and connection of relevant

building information, enabling seamless collaboration among all people in the project. The platform

is designed, using the latest Internet computing, cloud, mobile devices and social communication

technologies.

The bim+ Application Suite includes a core server API, which implements core functionality, i.e.

accept a client network call, transfer it to the core, get an answer from it, convert it to open data

interchange format (JSON in our case) and send it to the client. Clients can be any web, desktop, or

mobile applications which are capable to send HTTP REST requests to an API and accept answers in

JSON format.

Figure 21 - bim+ platform overview

4.2.2 bim+ API

The bim+ API provides RESTful services for accessing, creating, modifying and deleting different

levels of information in a building model on our bim+ platform. It connects the building project

information to a vast number of developers providing innovative Apps / applications that can

operate on the building models and information. There are four types of database operation defined

for manipulating the building content. i.e Create, Read, Update, Delete (CRUD) can be performed

against the resources (URI, which are building information in our case) which are essentially the

building blocks of REST.


Version 1.0

/62


The following HTTP methods implement these operations on persistent level:

Operation SQL HTTP

Delete the resource from the server DELETE DELETE

Retrieve the resource from the server SELECT GET

Create a resource on the server INSERT POST

Update the resource on the server UPDATE PUT

All necessary information for resource manipulation will be sent within a HTTP request. It includes

Resource identification (URL)

Data type / format (HTTP header)

Authentication information (HTTP header)

Operation, which will be performed against the resource (HTTP method)

The JSON objects which will be used as the bim+ data exchange format will thereby be based on the

IFC standard in terms of structure and naming21. The resource paths contain the team name and the

project name to support multi-tenancy.

The project slug (which should be provided during the creation of a project) should be provided as

part of the URL for accessing all the project relevant resources. This is also necessary to verify the

user’s access rights on the project in an early stage of processing the API call (before any business

data will be touched and any business logic will be executed).

4.2.3 bim+ Repository

In general, the input and output data format for all calls is JSON. We follow a wide accepted naming con-

vention like http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml#Property_Name_Guidelines

All communication uses https. Http requests will be rejected. The API calls follow the REST standard

(http://en.wikipedia.org/wiki/Representational_State_Transfer).

The following HTTP verbs are available and used for the described operations

HEAD

Can be issued against any resource to get just the HTTP header info.

GET

Used for retrieving resources – can either be a single object of a lift od objects.

POST

Used for creating resources, or performing custom actions.

PATCH

Used for updating resources with partial JSON data. Any kind of modifying operation on an existing

resource will use PATH.

21

Information about the IFC structure may be found at http://www.buildingsmart-tech.org/specifications/ifc-releases/summary

http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml#Property_Name_Guidelines

http://en.wikipedia.org/wiki/Representational_State_Transfer

http://www.buildingsmart-tech.org/specifications/ifc-releases/summary


Version 1.0

/62


PUT

Used for replacing resources or collections. PUT can be used as an alternative to PATCH

DELETE

Used for deleting resources.

Object Model

The bim+ class diagram (Figure 23 below) represents the API architecture, the object (classes)

structure, the services (methods) and their relations. It reflects:

the resulting JSON objects structure, which will be sent to a client upon an AJAX request with defined services

the class methods (services), which can be used by the client with HTTP requests (see BIM+ Services further below for detailed description).

Class methods here are not the real implemented class methods, but lists of HTTP methods

applicable to particular objects. Thus from the scheme one can see which objects are read only and

which ones can be modified / updated by the user.

Object name means that it can be used lower cased as a path (route) to a resource / collection. Fields

define which properties will be transferred to the client as resulting JSON string. If an element id is

provided in a collection, a particular object in the collection will be addressed and the detailed

information returned.

Object:

Figure 22 - bim+ object example

The object in the example shown in Figure 22 is read only and has method get(), implemented as

web service. This means that by a client it can be used as follows:

https://api.bimplus.net/v2/bimplus/disciplines/

Default HTTP method is get, so we must not specify it explicitly in the request. Server responses are

with a string, which automatically will be converted into JSON object:

{

"0f106af0-a919-44c5-b211-15bd5ef620b6": {

id: "0f106af0-a919-44c5-b211-15bd5ef620b6",

name: "<LOCALIZATION_STRING_ID>",

category: "/1/",

ifctype: null

},

{...},

...

}

Table 8 - bim+ Discipline object - JSON response

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171



Version 1.0

/62


Figure 23 - Web API Object Model and Services diagram

Team

A Team is a tenant/company which works on the building projects. The team has to be specified and

setup through the bimplus portal as so called slugs to present a clean URL. The team slug will be used

to know which tenant database to work on. All possible team related actions are addressed via the

bim+ Team Service.

Project

A Project is basically a holder which contains building models. The project slug (defined during the

creation of a project) should be provided as part of the URL which is necessary to verify the user’s

access rights on the project in an early stage of processing the API call (before any business data will

be touched and any business logic will be executed). All possible project-related actions are

addressed via the bim+ Project Service.

Model

A Model is roughly a technical 3D building plan.

bim+ Import Service imports existing models in the form of IFC or SketchUp files.

bim+ Model Service is used to address all the possible model related actions

http://www.bimplus.net/

http://en.wikipedia.org/wiki/Clean_URL#Slug/

http://en.wikipedia.org/wiki/Clean_URL/

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-TeamService

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-projectService

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-importService

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-modelService


Version 1.0

/62


Layer

A group of element types constitutes a layer. Layers are predefined. The detailed layered structure is

available in attachment of the Object Model. All possible layer-related actions are addressed via the

bim+ ElementType Service. However, note that an ElementType cannot belong to more than one

layer.

Object

Objects are the primary component of a project. They exist in two forms:

Node: Objects with no graphical representation

Geometry: Objects with graphical representation

All the possible object related actions are addressed via the bim+ Object Service. A project is also

basically an object.

Topology

Topology is a hierarchical tree representing all its child nodes. A topology tree consists of com-

ponents which can have a graphical representation (objects or elements) or components which do

not have a graphical representation (nodes). A topology tree can be obtained both on the project as

well as on the object level.

Use the bim+ Project Service for obtaining/filtering the project topology tree. This will yield the

topology nodes filtered to the sub-project level.

Element Type

ElementType describes the type of predefined building elements required to build a building (e.g.

wall, window, door etc.). Each element type has a unique id. The available element types can be

found under bim+ Element Types. All the possible element type related actions are addressed via the

bim+ ElementType Service.

Attachments

Attachments are mostly documents or any media files with additional information which can be

assigned to any project, object or issue. The detailed Attachments structure is available in

attachment of the Object Model.

Use the bim+ Project Service for creating/deleting an attachment or for getting all the attachments of a project

Use the bim+ Object Service for creating/deleting an attachment or for getting all the attachments of an object

Use the bim+ Issue Service for creating/deleting an attachment or for getting all the attach-ments of an issue

Use the bim+ Attachment Service for doing all the specific attachment related actions.

The bim+ communication service will use the BIM Model API as interfacing method with various BIM

repositories and map it into bim+ internal services to be able to handle the whole model on the bim+

to provide desired navigation / visualisation services and actions.

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-getProjectTopology


https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-elementTypeService

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-createAttachment

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-objCreateAttachment

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-createAttachmentForIssue

https://doc.bimplus.net/pages/viewpage.action?pageId=4459171#id-4.bim+APIReference-attachmentService


Version 1.0

/62


4.2.4 Client API

The following goals are targeted by the development of the client side web API:

Scalability

Modularity

Interface generality

Stability

Security

Independency of module deployment.

In order to achieve these goals, the following key principles are adopted for development:

RESTful architecture

Asynchronous data exchange between client and server

No sessions, i.e. no user data will be stored on the server

Client has no direct access to the database

Authentication token will be sent with every request

All requests are SSL encoded.

4.2.5 bim+ Multi Model Navigator Application

As already described in previous eeEmbedded deliverables of WP1 and WP2, the design of a building

is dedicated to optimize energy and operational costs carried out in 3 stages.

Step 1: Urban Design (LOD 100, Level of Detail - Solids with parameters)

Step 2: Early stage design (LOD 200, Level of Detail - divided into floors and facades defined with key design parameters)

Stage 3: Detailed design (LOD 300, Level of Detail - full BIM Model)

As a general user tool for each possible virtual energy lab configuration a bim+ based Multi-Model

Navigator is being developed in WP7. A sequence of the workflows exemplifying the position of the

Multi-Model Navigator in the design process might look as shown on Figure 24 below.

Figure 24 - Multi Model Navigator Workflow sequence

https://doc.bimplus.net/display/bimplus/2.6+Client+API


Version 1.0

/62


Functionality of the Navigator

The Navigator is in first place dedicated to compare the TO-BE and AS-IS KDP's project alternatives in

tabular form and display and highlight graphically the deviations from the nominal values. Selected

KDP values should be identified and displayed in the model on the appropriate places. More

information on the Navigator functionality is available in the deliverable reports of WP7.

Figure 25 - Multi Model Navigator Project and KDR Selection

Figure 26 - Multi Model Navigator: KDP selection and graphical interpretation


Version 1.0

/62


4.2.6 Implementations of the BIM Model API inside the bim+ repository

Section 4.2.2 above described the bim+ API. The developed BIM Model API specification is described

in https://github.com/GeorgDangl/eeE-BIM-API and in D8.1 [1].

There, the following main classes are defined:

Project - contains domains and models

Domain - generalized concept of discipline usage area like "Architect" "HVAC", "LCC Data" and similar

Model - part of project that can be contained in a single file. A model is assigned to a domain. Each model can exist in several versions, usually representing evolvement over time - that is, versions are not representing variants of the same model.

The general mapping between bim+ API and Model API is the following

Model API bim+

Project Project

Model Model (versioned)

In API called “Division”

Domain Discipline in API called Layer whereby each model can contain more

Layers/Domains (Arch, HVAC, Reinf, Rooms etc.) Are created automatically

based on the IFC element type

Table 9 - Mapping between bim+ and the BIM Model API

Creation of Projects may/will be done by server administration tools. Model is transferable as single

IFC file. Creation of Domains is handled implicitly during the Model create/Model upload service. The

following figures show how projects and models are handled by a bim+ client.

Figure 27 - Project selection list

https://github.com/GeorgDangl/eeE-BIM-API


Version 1.0

/62


Figure 28 - Model selection list

Figure 29 - Model viewer

The general mapping between Model API and bim+ API is done in the following way (valid for all

CRUD operations defined for manipulating the building content):

Project Level Services

Model API URL: {path-to-service}/{version}/projects

Example: https://example.com/eee/bim-api/0.4/projects

bim+ API URL: {path-to-service}/{version}/<team_slug>/projects

Example: https://api-stage.bimplus.net/v2/bimplus/projects

Domain Level Services

Model API URL: {path-to-service}/{version}/projects/project-id/domains

Example: https://example.com/eee/bim-api/0.4/ABCD/domains

bim+ API URL: {path-to-service}/{version}/<team_slug>/projects/<project_id>/disciplines

Example: https://api-stage.bimplus.net/v2/bimplus/projects/586b02be-43b8-4e27-b698-e067e85e38e2/disciplines

https://example.com/eee/bim-api/0.4/projects

https://api-stage.bimplus.net/v2/bimplus/projects

https://example.com/eee/bim-api/0.4

https://api-stage.bimplus.net/v2/bimplus/projects/586b02be-43b8-4e27-b698-e067e85e38e2/disciplines

https://api-stage.bimplus.net/v2/bimplus/projects/586b02be-43b8-4e27-b698-e067e85e38e2/disciplines


Version 1.0

/62


Model Level Services

Model API URL: {path-to-service}/{version}/projects/project_id/domains/domain_id/models

Example: https://example.com/eee/bim-api/0.4/ABCD/domains/EFGH/models

bim+ API URL: {path-to-service}/{version}<team_slug>/projects/<project_id>/divisions

Example: https://api-stage.bimplus.net/v2/bimplus/projects/743a24f9-baaa-41b9-90b3-91717238043c/divisions

Each API sends as response body a similar, yet different content. To be able to communicate

between different servers a minimal set of common properties called Metadata was defined inside

the BIM Model API:

Project Meta Data - Meta data for a model in the server Domain Meta Data- Meta data for a model in the server Model Meta Data - Meta data for a model in the server

These must come as response for each mapped API call.

The main communication token between the bim+ API and the Model API are project_id, domain_id

and model_guid (as described in the Model API) which are mandatory for the Model API calls. These

will be stored on the bim+ side as Attribute of the bim+ Project, Division (Model) and Layer (Domain).

Internally, bim+ will use as Object identification bim+ server generated GUID’s. Thereby is ensured,

the relation between bim+ and Model API objects will be kept and all the GUID’s remain unique

inside a project.

4.2.7 Implementations of the BCF REST API - Client

BCF is a format for managing issues on a BIM project. RESTful BCF-API supports the exchange of

BCFv2 issues between software applications.

Goal of the BCF API usage and their implementation in the bim+ framework is to enable project

partners to create issues, manage them online and evaluate them in the context of the actual BIM

model. As bim+ API also has a RESTful architecture, implementation of the BCF API is based on the

mapping and synchronizing of the corresponding services.

In the eeEmbedded architecture, BIM--it is used as BCF Server (see section 4.3 below). In particular,

this means that a bim+ client will call the bim+ server to send/receive BCF, and bim+ as BCF client will

call the BIM--it server using related BCF REST API server services.

In general, after connection to the BCF server a set of corresponding BCF API services will be

available to retrieve the project list and topics (issue) lists.

Basically a BCF issue holds a description of the issue, a status, links to a BIM model and objects, a

picture of the issue and a camera orientation. For all this an appropriate BCF API service will be used

to obtain a full state of the actual issue(s) from a given project.

On the bim+ side, the BCF API calls will be automatically internally mapped and synchronized with

bim+ API calls to interpret the BCF issues inside bim+ services.

https://example.com/eee/bim-api/0.4/ABCD/domains/EFGH/models

https://api-stage.bimplus.net/v2/

https://api-stage.bimplus.net/v2/bimplus/projects/743a24f9-baaa-41b9-90b3-91717238043c/divisions

https://api-stage.bimplus.net/v2/bimplus/projects/743a24f9-baaa-41b9-90b3-91717238043c/divisions

https://github.com/BIMit/ModelAPI/blob/master/doc/repository-services-01/a_schemata/README.md

https://github.com/BIMit/ModelAPI/blob/master/doc/repository-services-01/a_schemata/project_meta_data.md

https://github.com/BIMit/ModelAPI/blob/master/doc/repository-services-01/a_schemata/domain_meta_data.md

https://github.com/BIMit/ModelAPI/blob/master/doc/repository-services-01/a_schemata/model_meta_data.md

https://github.com/BuildingSMART/BCF-API



Version 1.0

/62


Figure 30 - bim+ Multi Model Navigator Workflow

Example

Retrieve comments from the BCF Server for a given project and issue and create a new comment

inside topic

Step 1: Retrieve Project from BIM—it Server

BCF API Project service:

URL: {path-to-service}/bcf/{version}/projects Example: https://bim--it.net/bcf/1.0/projects

{

"guid":"16550c05-7bac-4446-9718-9e391ae5e428",

...

}

Table 10 - BIM--it projects response

Figure 31 - Project interpretation on the Bim--it server


Version 1.0

/62


bim+ API mapping and synchronization – bim+ Project service:

URL: {path-to-service}/{version}/projects/project_id

Example: https://api-stage.bimplus.net/v2/projects/d7dc4f92-982d-457e-8c29-86de7d0cb6b2

{ "BCFguid":"16550c05-7bac-4446-9718-9e391ae5e428", ... }

Table 11 - bim+ BCF project response

Figure 32 - Project interpretation on the bim+ server

Step 2: Retrieve Topic from BCF Server for the given project – BCF Topic (Issue) service:

URL: {path-to-service}//bcf/{version}/projects/{project_id}/topics

Example: https://bim--it.net/bcf/1.0/projects/16550c05-7bac-4446-9718-9e391ae5e428/topics

{

"guid": "92fc5ad2-7e16-478d-aaae-2af87221c8f5",

"title": "Example topic 1",

...

}

Table 12 - BIM--it topic response

Step 3: Retrieve Comment from BCF Server for the given Topic – BCF Comment service:

URL: {path-to-service}/bcf/{version}/projects/{project_id}/topics/{guid}/comments

Example: https://bim--it.net/bcf/1.0/projects/16550c05-7bac-4446-9718-9e391ae5e428/topics/ 92fc5ad2-7e16-478d-aaae-2af87221c8f5/comments

https://bim--it.net/bcf/1.0/projects/16550c05-7bac-4446-9718-9e391ae5e428/topics


Version 1.0

/62


[

{

"guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",

"status": "open",

"date": "2013-10-21T17:34:22.409Z",

"author": "[email protected]",

"comment": "Original comment",

"topic_guid": "92FC5AD2-7E16-478D-AAAE-2AF87221C8F5"

},

...

]

Table 13 - BIM--it comment response

Figure 33 – BCF Topic interpretation on the BIM--it server

Following: Automatic bim+ API mapping and synchronization.

Step 4: Retrieve corresponding bim+ Topic: bim+ Topic service

URL: {path-to-service}/{version}<team_slug>/issues/<issue_id>

Example: https://api-stage.bimplus.net/v2/bimplus/issues/823f1e91-e7c6-49fd-8ed4-db161537d425

{

"BCFIssueId": "92fc5ad2-7e16-478d-aaae-2af87221c8f5",

...

}

Table 14 - BCF topic as bim+ issue response

https://api-stage.bimplus.net/v2/bimplus/issues/cb96a9b1-48c9-4d97-8c9e-262476c1c6b2


Version 1.0

/62


Figure 34 – BCF Topic interpretation on the bim+ server

Step 5: Create a new comment and update – bim+ Issue Comment Service:

URL: {path-to-service}/{version}<team_slug>/issues/<issue_id>/comments Example: https://api-stage.bimplus.net/v2//issues/823f1e91-e7c6-49fd-8ed4-db161537d425/comments

{ "BCFIssueId": "92fc5ad2-7e16-478d-aaae-2af87221c8f5", "text": "New Comment", "createdAt": "2015-12-16T08:15:15.1932853+00:00", ... }

Table 15 - bim+ comment response

Figure 35 – BCF Topic with cmments interpretation on the bim+ server

https://api-stage.bimplus.net/v2/issues/cb96a9b1-48c9-4d97-8c9e-262476c1c6b2/comments


Version 1.0

/62


Step 6: Synchronize with BIM-it server – BCF Comment service

URL: {{path-to-service}//bcf/{version}/projects/{project_id}/topics/{guid}/comments

Example: https://bim--it.net/bcf/1.0/projects/16550c05-7bac-4446-9718-9e391ae5e428/topics/92fc5ad2-7e16-478d-aaae-2af87221c8f5/comments

{

"verbal_status": "closed",

"status": "closed",

"comment": "New Comment"

...

}

Table 16 - BIM--it comment response

Figure 36 – BCF Topic with comments interpretation on the BIM--it server

https://bim--it.net/bcf/1.0/projects/16550c05-7bac-4446-9718-9e391ae5e428/topics/92fc5ad2-7e16-478d-aaae-2af87221c8f5/comments

https://bim--it.net/bcf/1.0/projects/16550c05-7bac-4446-9718-9e391ae5e428/topics/92fc5ad2-7e16-478d-aaae-2af87221c8f5/comments


Version 1.0

/62


4.3 BIM--it

During the specification of the BCF API, iabi developed BIM--it with the intent to create a fully BCF

compatible, cloud based collaboration platform that is accessible by any client with a web browser

and internet connection.

BIM--It is fully compatible to BCF and supports the BCF API as well as the BIM Model API completely.

It is available at https://bim--it.net.

As a result of that development, the BIM--it platform is both used as a web application acting like a

regular client which consumes services but it also offers server capabilities and provides access to

BCF services and a BIM Model repository for external clients to connect to.

4.3.1 Teams & Projects in BIM--it

BIM--it is structuring collaboration projects via the concepts of teams, where users can be assigned

to be Team Managers. These users have the permissions to create new projects and assign the

responsible BIM Managers.

Figure 37 - BIM--it Team Management section

In BIM--it, a project represents what would map to a real building process. Project access is

controlled in two ways. Users that manage a team have access to all projects hosted within that

context. This is useful if, for example, a team represents a user of the app like a construction

company. They would have few responsible employees that are granted the Team Manager role to

cultivate their projects. These Team Managers would in turn assign roles to BIM Managers for each

https://bim--it.net/


Version 1.0

/62


respective project and have the BIM Managers take care of running and coordinating the actual

project.

When logged in, there is a section called “Start” that shows an overview of all projects the currently

logged in user has access to. Additionally, users, unread topics and unresolved issue assigned to the

logged in user are also displayed.

Team Managers have the capability to export whole projects as BCF XML files for archiving or

exchange purposes.

4.3.2 Managing Projects as BIM Manager

Users that have been granted the role of BIM Manager in at least one project (see Figure 37) do see a

new tab in the menu called “BIM Manager”. In this section, they have a list of all the projects where

they are granted rights to manage.

The BIM Manager section offers three distinct functionalities, the first one being the configuration of

the project extensions (see section 2.2.1) as shown in Figure 38. It allows the manager to modify the

six categories that are specified by the BCF Project Extensions. Since BIM--it was written to be fully

compliant to BCF a lot of its functionality is driven by the extensions. For example, when users create

new topics, the platform makes sure that they comply with the specified extensions. That means,

users in the web interface are only presented values to choose from that have been defined by the

BIM Manager.

Figure 38 - BIM Manager view on project extensions

Another topic that is managed by the BIM Manager is the fine tuning of who is able to access a

project. In general, users are added or removed from a project via the “users” property of the Project

Extensions. If users are not yet registered on the platform, BIM Managers are presented a choice to

send an invitation email to the user. The user will then be added to the project after having

registered on the platform.


Version 1.0

/62


Projects that call for a more granular access matrix can so be configured the “User Access Rights”

section as shown in Figure 39. Basically, the BIM Manager may choose which labels respectively

domains a single user can access. This might be used when users do not want to have HVAC or

energy experts access cost related information but still be able to collaborate on the geometric

building models and view simulation results. The user access matrix is following the “at least one

required” authorization principle, meaning that when a topic is tagged with multiple labels, any user

that has access to at least one of the labels will be able to access the topic.

Figure 39 - BIM Manager view on project repositories and user access rights

Interaction with models is also controlled by the BIM Manager. The “Manage Repositories” tab

provides an overview of all repositories that are attached to the project. By default, the integrated

BIM Model API repository of BIM--it is enabled for every project. Currently, any other repository is

attachable to a project as long as it is conforming to the BIM Model API specification, such as the

EDM Model server for instance. Likewise, BIM--it does have an integration with Dropbox. Users must

link their account with Dropbox (which works in a similar way as BCF clients connecting to BIM--it)

and are then allowed to use their Dropbox for data uploads or retrieval. They can also share models

via their Dropbox account with the project, which is even possible when the sharing user is not

currently connected. All interactions with this repository do happen via the BIM--it interfaces and

require no external software.

4.3.3 BIM Models

The platform supports arbitrary models to be uploaded to its internal repository. This is useful when

users want to share data such as native models, documents or simulation results that cannot yet be

handled by the platform. Extended functionality regarding IFC2x3 and IFC4 is offered. The

repositories tab as shown in Figure 40 is concentrating all the functionality regarding interfacing with

the BIM Model API and is seamlessly integrated in BIM--it.


Version 1.0

/62


Figure 40 - Repositories section in BIM--it

Figure 41 shows the form where the user uploads a model, in this case a regular IFC2x3 building

model. If the file is recognized to be an IFC model that can be processed by the server, it will be made

available also in the web based 3D model viewer. Additionally, models are versioned in the platform.

When a model changes, the user may decide to keep the old data still in place on the server but

upload a new revision. By default, only the newest version of any model is shown to the user with

the option to look at and even search for older revisions.

Figure 41 - The upload of a model in BIM--it


Version 1.0

/62


Industry Foundation Classes models can be directly visualized within the browser without the need of

any prior software installations from the end user. Any modern mobile or desktop browser meets the

requirements to draw the 3D models and let the user interact with them. Figure 42 shows the model

file that has been uploaded from the menu in Figure 41. Users are able to manipulate the current

view, such as setting the visibility of components or regions as well as selecting and highlighting

certain parts of the model. Collaboration with a model context is also possible, where users can

either create new BCF topics based on the current viewer camera or add new viewpoint information

to an existing topic. For example, it is possible to identify a problem, create a topic for that and then

provide additional viewpoints showing the location of the issue from different angles and with

different components, like two viewpoints that each show only one component of a detected clash.

The technology to convert native IFC data to a format that can be visualized in the browser is

provided by apstex22, which is a Java based library that is capable of transforming IFC geometry data

into a JSON format for browser visualization.

Figure 42 - The uploaded model in the web viewer

22

http://www.ifctoolsproject.com


Version 1.0

/62


4.3.4 Collaboration View

The main section for user collaboration is the “Topic” tab in the project view. As seen in Figure 43,

BIM--it presents its users a detailed view for each issue. The navigation menu to the left provides an

overview of all topics currently in the project, where older topics are dynamically retrieved from the

server when either the user scrolls down to the end of the menu or a search does not return any

more results in the currently loaded list. With the advanced search feature, users can restrict the

view to show only topics with a certain label, status or type. Additionally, issues that are marked as

resolved or hidden (like topics that should only be used from a client for automatic processing) can

be shown on demand.

The right hand side shows an example of how a topic is presented in BIM--it.

Figure 43 - Detailed view of a single topic in BIM—it

Figure 44 shows the form used to create new topics. Additionally, if the topic creating process is

initiated by the viewer, a screenshot of the current model is also attached to the topic. To supply

more information, users may also choose to append one or more images to a topic, even after it has

been created. This is useful when the project is already in the construction or the FM phase, since

mobile devices allow the capturing of issues with an attached photo directly on site to ensure

optimal collaboration capabilities and issue tracking without having to rely on multiple, not

synchronized systems.

Additionally, new topics can be created by importing BCF XML files via the “Create New Topic” dialog.


Version 1.0

/62


Figure 44 - The creation form of a new topic in BIM--it

When a topic is newly created, modified or commented on, logged in users that have access to it see

a notification badge in the upper right corner of the screen as shown in Figure 45. This works without

having to reload the page and, on clicking, directly navigates to the appropriate topic.

Figure 45 - Notification about unread topics in the upper right corner


Version 1.0

/62


Additionally, unread topics can be presented in the navigational menu (Figure 46). They are

highlighted for quick identification by the user. Upon selecting an unread topic, it is automatically

marked as read on the server. In the shown case, a new comment has been submitted to the topic.

Upon clicking, the detailed view will indicate a threaded history of the communication on the

selected issue (Figure 47). Furthermore, any topic may be exported as a BCF XML file.

Figure 46 - Unread topic highlighted in the topic navigation menu

Figure 47 - Topic with an attached comment


Version 1.0

/62


4.3.5 Project History and Timeline

An advantage of using a specialized format such as BCF for collaboration processes in a building

process is BCF’s tracking capability. This can be used to track which topics are currently active, when

specific topics have been marked as finished and much more. Figure 48 shows an example of the

timeline as presented in BIM--it. The topic selection is synchronized with the navigation menu, so the

highlighted topic in the timeline is also the currently selected topic for the detail view. This binding

works in both directions.

Additionally, the topic in the lower left edge is marked as being complete, since it does not extend

until the current time but is already shown as having ended on December the 18th. Quick zooming

capabilities allow for a fast overview of either current or historical project states and allows for

targeting a specific point in time.

Figure 48 - Timeline of the eeEmbedded sample project in BIM--it

4.3.6 Architecture and Technology Background

The application has been created as a web application with Microsoft .Net as the server side

framework. To create a responsive end user experience, many functions are performed on the client

side in the browser via JavaScript to reduce the amount of page reloads and thereby introduced

delays.

Two types of persistent data storage are used. Relational, structured data is kept in a relational

database system and unstructured or loosely structured data is kept in a document storage database.

One of the main development goals was to use the standardized APIs, BCF and BIM Model, as much

as possible to enable a seamless integration into the eeEmbedded platform. This means that all the

functionality that can be server by the BCF REST API is used as such. Most of the features in the

collaboration section is utilizing the BCF API with only very few, non-critical features relying on

custom extensions to the API.


Version 1.0

/62


4.3.7 Connecting with External Clients to BIM--it

Users that have requested to be granted Developer role are able to access a section that allows them

to register applications with BIM--it, which then enables them to create client applications that

access the BIM--it features via the BCF REST API as well as the BIM Model API. Clients do have to

conform to the OAuth223 standard for authentication, meaning that they must ensure that there is a

separation regarding user credentials. With OAuth2, user credentials are kept secret from the clients

themselves. This ensures that no malicious client can extract the login information and impersonate

a user. Furthermore, the resources and scopes a certain client can be accessed may be limited or

configured by the user on the BIM--it platform without having to change settings in the client.

Developers must provide some required information when they create a client to allow for client

identification.

Figure 49 - BIM--it Developer section

Additionally, BIM--it is enabled to also accept connections from anonymous clients. This is because it

is likely that due to having many different BCF servers in the future, clients will often not be

previously introduced to servers. An anonymous client does work just like a regular OAuth2 client,

with the exception that the client itself provides its information and servers may refuse it or enforce

a stricter access policy regarding anonymous clients.

When a client intends to connect to BIM--it, the OAuth2 flow as specified is followed. This means

that the user is sent in his web browser to BIM--it where he must authorize with his credentials and

approve the client to be allowed to connect. Then, BIM--it sends an access token back to the client

that can be used for further connections. This ensures that the user never has to enter his credentials

in a client but only on the BIM--it web application itself. Figure 50 shows the screen that is presented

to the user when a client wants to connect in his name. The lower part of the page shows

information about the client, while the fields “Client ID” and “Client State” are values provided by the

client and are just shown here informational to the user.

23

OAuth2 is an open standard that specifies a delegation process to handle accessing secured resources from a client without having to hand the client the users credentials but only an intermediate token that limits the actions the client can do. Typically, web services (Microsoft, Google, Dropbox and others) offer an OAuth2 login to keep their clients login credentials secure. [16]


Version 1.0

/62


Figure 50 - BIM--it page to connect an OAuth2 client

4.3.8 BCF Server

iabi created a BCF server implementation on top of its BIM--it collaboration web app. The API is

integrated with the BIM--it application, meaning users do only need to register once and have the

same level of access to their projects regardless whether they use the web application or a third

party, BCF compatible client. The relational data storage was modeled with full support for BCF in

mind. An excerpt from the entity relationship diagram is shown in Figure 51, where the main tables

for storing topics as well as some of the dependencies realized via foreign keys are shown.

Figure 51 - Relational data model for the storage of BCF topics in BIM—it


Version 1.0

/62


4.4 Model Servers

In [1, p. 65f], the Repository API that is used within eeEmbedded is described. In short, repositories

are services that support CRUD operations for managing structured data, for example IFC model files

with attached metadata. The BIM Model API was developed to have an independent and open

service specification available to be used for eeEmbedded and is offering basic functionality that was

identified as being necessary for interfacing with repositories in regard to storing and retrieving

building model data and related information. A description of the BIM Model API service can be

found at https://github.com/BIMit/ModelAPI and in [1].

There are two implementations supporting the BIM Model API that are used within eeEmbedded,

EDM Model Server and BIM--it. The bim+ implementation will support connection to BIM Model API

servers via the standardized API but will not offer client services other than its existing functionality

(see section 4.2.6).

On top of the BCF capabilities that are provided by BIM--it, the BCF server offers a fully compatible

BIM Model API implementation. It was deemed necessary to implement such functionality in order

to allow simulation workflows without having to rely on external services during the testing process.

The data storage itself is using a document database to store metadata as the model and a binary file

storage system to store the actual models.

https://github.com/BIMit/ModelAPI

D8.2 Collaboration Methods - Conclusion

Version 1.0

/62


5 Conclusion

This deliverable shows that, using adequate technologies and collaboration methods, processes

required by the eeEmbedded platform are possible to set up and perform with the described

technologies and tools. Especially regarding D8.1, where a big variety of platform tasks has been

identified and detailed, the tools that exist in combination with the components developed during

the process of this deliverable will support the required workflows.

Progress has not only been made in specifying the data standards and technology conventions but

also very much in actual implementations of the eeEmbedded platform, fully preparing the project

for the planned testbed.

With additional identification of process parts that need to be modelled within automated

collaborative processed and the support of the Scenario Manager in enforcing processing rules, the

collaboration methods for eeEmbedded will be incorporated in the software products to be

developed leading to a coherent, seamlessly integrated and interoperable energy lab platform

environment.

D8.2 Collaboration Methods - References

Version 1.0

/62


6 References

[1] A. Sukumar, A. Tøn, K. Linhard, E. Mrazek, M. Mosch and P. Katranuschkov, eeEmbedded - D8.1:

SOA Platform Architecture, Brussels: eeEmbedded Consortium, 2015.

[2] Wikipedia: Representational state transfer, 9 12 2015. [Online].

Available: https://en.wikipedia.org/wiki/Representational_state_transfer. [Accessed 10 12 2015].

[3] buildingSMART: BCF intro, 2015. [Online].

Available: http://www.buildingsmart-tech.org/specifications/bcf-releases. [Accessed 10 12 2015].

[4] T. Liebich, Proposal for BIM Snippet Content - IfcPropertySets, Munich, BCF Hackathon, 2015.

[5] N. T. T. Van, A Proposal for a Management and Collaboration Model Within the Building

Information Modeling Design Phase, Munich University of Applied Sciences - Master Thesis,

Munich, 2015.

[6] Wikipedia: Business Process Model and Notation, 11 12 2015. [Online].

Available: https://en.wikipedia.org/wiki/Business_Process_Model_and_Notation.

[Accessed 16 12 2015].

[7] R. Guruz, G. Calleja-Rodríguez and M.-C. Geißler, eeEmbedded D2.1: Holistic multi-disciplinary

Key Point-based design framework, © eeEmbedded Consortium, Brussels, 2015.

[8] R. Scherer and S.-E. Schapke, A distributed multi-model-based Management Information System

for simulation and decision making on construction projects, Advanced Engineering Informatics,

2011.

[9] ifcDoc Tool, [Online]. Available: http://www.buildingsmart-tech.org/specifications/specification-

tools/ifcdoc-tool. [Accessed 11 01 2016].

[10] M. Gürtler, K. Baumgärtel and R. Scherer, Towards a Workflow-Driven Multi-model BIM

Collaboration Platform, in: Risks and Resilence of Collaborative Networks, IFIP Advances in

Information and Communication Technology (Vol. 463), http://doi.org/10.1007/978-3-319-

24141-8, Springer International Publishing, pp. 235-242.

[11] R. Scherer and R. Guruz, Towards a KPI-controlled holistic design method for eeBuildings,

in: Proceedings of European Conference on Product and Process Modelling, CRC Press, 2014,

pp. 879-885.

[12] D. Hollingsworth, The Workflow Reference Model, Workflow Management Coalition, 1994.

[13] Activiti, [Online]. Available: http://activiti.org. [Accessed 11 01 2016].

[14] Wikipedia: SOAP, 09 12 2015. [Online]. Available: https://en.wikipedia.org/wiki/SOAP.

[Accessed 10 12 2015].

[15] Wikipedia: Zip (file format), 05 12 2015. [Online].

Available: https://en.wikipedia.org/wiki/Zip_(file_format). [Accessed 16 12 2015].

[16] Wikipedia: OAuth, 15 12 2015. [Online]. Available: https://en.wikipedia.org/wiki/OAuth.

[Accessed 21 12 2015].

[17] Wikipedia: Open Data Protocol, 05 12 2015. [Online].

Available: https://en.wikipedia.org/wiki/Open_Data_Protocol. [Accessed 17 12 2015].


Version 1.0

/62


List of Figures

Figure 1 - Structure of the Service Oriented Architecture design in eeEmbedded [1, p. 10] ................. 7

Figure 2 - Scenario Manager and bim+ Navigator connected via BCF over the BIM--it server .............. 7

Figure 3 - Structure of the BCF data format .......................................................................................... 10

Figure 4 - BCF XML Content - Top Level ................................................................................................ 12

Figure 5 - BCF XML Content - Topic Folder ............................................................................................ 13

Figure 6 - The highlighted building roof in BIM—it ............................................................................... 15

Figure 7 - Creation of a BCF Topic in BIM--it ......................................................................................... 15

Figure 8 - The issue opened in BCFier ................................................................................................... 16

Figure 9 - The issue imported in Solibri Model Checker ....................................................................... 16

Figure 10 - Basic example of a process modelled in BPMN .................................................................. 19

Figure 11 - Enriched process diagram with attached collaboration information ................................. 20

Figure 12 - ScenarioManager use cases ................................................................................................ 24

Figure 13 - Application of ScM together with a BCF Server .................................................................. 25

Figure 14 - Multimodel approach with multiple domain models and link models connecting these

elementary models ................................................................................................................................ 26

Figure 15 - Output of Process Map based on a) conventional single model (e.g. IFC), b) multimodel

approach and c) process-centric multimodel approach ....................................................................... 26

Figure 16 - Single model BCF collaboration (left hand) and knowledge-based multi-model

collaboration (right hand) ..................................................................................................................... 27

Figure 17 - Workflow-driven multi-model BIM Scenario Manager ....................................................... 28

Figure 18 - Excerpt of an UML sequence diagram of the workflow execution ..................................... 29

Figure 19 - ScenarioManager GUI, left side: Project Explorer, right side: Project Settings Palette for

defining BPMs, bottom: Properties to manage activities in processes ................................................. 30

Figure 20 - BCF message view in ScenarioManager .............................................................................. 30

Figure 21 - bim+ platform overview ...................................................................................................... 31

Figure 22 - bim+ object example ........................................................................................................... 33

Figure 23 - Web API Object Model and Services diagram ..................................................................... 34

Figure 24 - Multi Model Navigator Workflow sequence ....................................................................... 36

Figure 25 - Multi Model Navigator Project and KDR Selection ............................................................. 37

Figure 26 - Multi Model Navigator: KDP selection and graphical interpretation.................................. 37

Figure 27 - Project selection list ............................................................................................................ 38

Figure 28 - Model selection list ............................................................................................................. 39

Figure 29 - Model viewer ...................................................................................................................... 39

Figure 30 - bim+ Multi Model Navigator Workflow .............................................................................. 41

Figure 31 - Project interpretation on the Bim--it server ....................................................................... 41

Figure 32 - Project interpretation on the bim+ server .......................................................................... 42

Figure 33 – BCF Topic interpretation on the BIM--it server .................................................................. 43


Version 1.0

/62


Figure 34 – BCF Topic interpretation on the bim+ server ..................................................................... 44

Figure 35 – BCF Topic with cmments interpretation on the bim+ server ............................................. 44

Figure 36 – BCF Topic with comments interpretation on the BIM--it server ........................................ 45

Figure 37 - BIM--it Team Management section .................................................................................... 46

Figure 38 - BIM Manager view on project extensions........................................................................... 47

Figure 39 - BIM Manager view on project repositories and user access rights .................................... 48

Figure 40 - Repositories section in BIM--it ............................................................................................ 49

Figure 41 - The upload of a model in BIM--it ........................................................................................ 49

Figure 42 - The uploaded model in the web viewer .............................................................................. 50

Figure 43 - Detailed view of a single topic in BIM—it ........................................................................... 51

Figure 44 - The creation form of a new topic in BIM--it ........................................................................ 52

Figure 45 - Notification about unread topics in the upper right corner ............................................... 52

Figure 46 - Unread topic highlighted in the topic navigation menu ..................................................... 53

Figure 47 - Topic with an attached comment ....................................................................................... 53

Figure 48 - Timeline of the eeEmbedded sample project in BIM--it ..................................................... 54

Figure 49 - BIM--it Developer section ................................................................................................... 55

Figure 50 - BIM--it page to connect an OAuth2 client .......................................................................... 56

Figure 51 - Relational data model for the storage of BCF topics in BIM—it ......................................... 56


Version 1.0

/62


List of Tables

Table 1 - BIM Snippet content that transports element property set data (simplified) [4] .................. 11

Table 2 - Xml Content of a BCF XML Topic Entry (simplified) ................................................................ 13

Table 3 - Xml Content of a BCF XML Viewpoint .................................................................................... 14

Table 4 - Types of BIM functions (modified) [5, p. 33] .......................................................................... 18

Table 5 - Unfiltered BCF API topics response ........................................................................................ 21

Table 6 - BCF topic resource response after an additional issue was created ...................................... 22

Table 7 - BCF topic resource response with the applied filter .............................................................. 22

Table 8 - bim+ Discipline object - JSON response ................................................................................. 33

Table 9 - Mapping between bim+ and the BIM Model API ................................................................... 38

Table 10 - BIM--it projects response ..................................................................................................... 41

Table 11 - bim+ BCF project response ................................................................................................... 42

Table 12 - BIM--it topic response .......................................................................................................... 42

Table 13 - BIM--it comment response ................................................................................................... 43

Table 14 - BCF topic as bim+ issue response ......................................................................................... 43

Table 15 - bim+ comment response ...................................................................................................... 44

Table 16 - BIM--it comment response ................................................................................................... 45

eeembedded d8.2 collaborative...

Documents