Integration with the Catenda Hub/BIM Sync system (CDE environment)

Introduction

The document describes how to integrate the AMAGE system with the CDE BIMSync/Catenda Hub environment. This environment allows you to store, share and work on models and documentation in accordance with the BIM process.

The AMAGE system has the ability to directly integrate with the CDE environment and exchange information using API interfaces. This allows you to transfer data between systems and visualize 3D models directly in the CDE environment.

In the process of creating the integration, Catenda changed the names of its products. BIMSync and Catenda Hub are sometimes mentioned in this documentation/system. This is the same product/app.

Establishing communication and initial configuration

In order for the AMAGE system to have direct access to projects stored in the CDE environment, appropriate communication and authorization data must be configured. We do this in two places:

in the CDE environment, we define a new application for data exchange and set the so-called return address
in the AMAGE application, we enter the authorization data and carry out the initial authorization

Application configuration in the Catenda Hub/BIMSync environment is performed in the user’s settings view.

Figure 1. Access to user settings

In it, we go to the user settings view and the Applications application. We define a new application there. Going to its details, we receive information about communication keys AND we have the option to enter the AMAGE system return address (so-called RedirectUrl). It is to this address that the Catenda Hub system will send information about the correct authorization together with a temporary key to authorize individual queries.

Figure 2. CDE BIMSync preconfiguration

In the case of the AMAGE system, in the RedirectUrl address, enter the address of our instance with the ending integrations/auth-bimsync, e.g. https://demo.amagesystems.net/instance-002/integrations/auth-bimsync. This will allow for proper feedback. ATTENTION. The address must be available on the external Internet network.

The AMAGE system is configured in the configuration interface. Go to it and select the Add-ons\BIM CDE section. In it, as the first option, we choose the CDE environment to which we are integrating. In this case, Catenda BIM Sync.

Figure 3. CDE environment selection

Then, in the tab concerning the configuration of this environment, we define the access data. We enter the same data that we entered in the CDE application environment. parameters:

Client ID - client ID
Client Secret - client’s secret code
Redirect URI (integrations/auth-bimsync) - address. We enter the same address as entered in the catenda interface.

Figure 4. Configuration of integration parameters

After this configuration, we can start using the data. In order to access them, the user must periodically authorize himself, i.e. indicate his authorization to use the interface.

The access data of the application allows the exchange of data between systems. User authorization, on the other hand, allows access to specific data (projects, models) in accordance with the permissions of a given user. Please refer to the Manufacturer’s documentation for details of access and necessary user permissions.

The AMAGE interface also shows information about the currently logged in/authorized user and actions related to the account and main settings.

Authorized as - if user authorization is active, the user name from the BimSync system will be displayed
Authorize - action that allows you to authorize the user. Use it in the early stages. The system will also remind you in the main interface if the authorization expires.
Forget - forget authorization codes. Another authorization will be required in the Catenda system using the 'Authorize' button
Information - technical information about the currently logged in user

Project selection:

Project + refresh - setting with which project in the CDE application this AMAGE instance is paired. To get the current list of projects, press the Refresh button and then select the project. This project will be saved in AMAGE and every user will be paired with it in the main interface of the application (if they have access to it).

The first authorization will result in redirecting the user to the Catenda website and the need to log in using the user interface, i.e. entering the login/password. If the authorization is correct, then each subsequent authorization for a given user will be carried out without the need to display the login window. In this case, the AMAGE system will simply reload visually for the user.

Authorization errors

In the case of authorization, two types of errors may occur:

incorrect data of the application defined in BIMSync - incorrectly copied data, application with disabled access, etc.
no user authorization - authorization error or time of active authorization expired

In the first case, authorization errors may occur. Messages from the AMAGE system may convey specific information and may also indicate a specific communication error. This will facilitate further diagnostics and possible recognition of the error code when contacting the manufacturer’s support.

Figure 5. Communication error with the Catenda system (missing application keys)

Figure 6. Authorization error - user re-authorization required

CDE browsers

After going to the main interface of the application, the BIM CDE navigator will be added to the main menu in the Integration section. This will bring up the CDE interface.

Figure 7. CDE browser main menu

In the system we have the possibility to:

Browsing the list of IFC models, their visualization and integration with the AMAGE system
Browsing CDE libraries, e.g. a list of documents and actions on them
Browsing the entire design view associated with all models available in the CDE

IFC models

Figure 8. Model view

The model view allows you to view the list of active models. When you select any model in the right part of the view, it will be loaded in the 3D viewer. The browser allows navigation identical to the view of the CDE environment.

A context menu is available for each model:

Figure 9. Model context menu

Available actions:

View model (3D) - visualization of a given model in the integrated viewer
Import as resources - call the resource importer. Data transfer from a given IFC model to the AMAGE system
View 3D model (new window) - displaying the model in a separate pop-up window

Resource import is described in a separate Howto document and in the main system documentation. This operation allows you to import the structure/parameters contained in the IFC model into the application structure as a complete and comprehensive data structure. Then, already in the AMAGE application, we can use the system’s functions regarding supervision, inspection or control/documentation in order to expand the functions of the BIM process.

IFC document libraries

The integrated document viewer allows you to view any library created in the Catenda Hub/BIMSync software. The interface allows you to browse all libraries. One of the default libraries is a document/file archive.

The browser interface allows access to system data.

Figure 10. Library/document browser

The interface is divided into two parts. In the first one, we select the CDE library we are browsing. There, I also have the option of going to the parent folder during navigation and going to the root directory of a given library.

Below is a directory/file browser downloaded directly from the CDE. Each entry has the ability to perform several actions available in the main buttons and in the context menu.

Figure 11. Context menu

Up - moves to the parent directory
Preview - file preview - internal viewers for PDF files and images.
Download - Download files to a local drive
Copy to resource - downloading the file and uploading it to a specific resource in the system.
Copy to type - download the file and upload it to a specific type in the system

Using these operations, we can transfer data from a selected library to a specific resource/type in the system, e.g. after importing IFC models.

Full project view

The view allows you to visualize all models in the system using the integrated viewer.

Figure 12. 3D view (full screen)

Import of structured data from IFC v.2x3 and COBie formats - import of IFC models to the AMAGE system.

This Howto is based on system version 1.21.0.0 (03.2023) and presents features that may not be available on your system. Ask AMAGE to provide this functionality.

Due to ongoing development of the system, some screens or configuration files may look slightly different, but will still retain the full functionality described here. This does not affect the core functionality described in this document.