Introduction

This article describes simple API that can be used on client side. The full server API is always available under https://<your-hdc-host>/apidocs

Running Viewer in "embedded" headless mode can be achived by adding viewport=EmbeddedViewer to HDC server call. 

http://localhost:8080/client/?viewport=EmbeddedViewer

 Your request must be pre-authenticated, otherwise it will be redirected to main login screen. After login, user might be redirected to full layout.

Controlling Toolbar Visibility

since handling of embedded mode must be reviewed (pre-authentication, navigating back, avoiding login screen or full app load), 

a simple parameter was added to control toolbar visibility in embedded view:

?viewport=EmbeddedViewer&toolbar=true

when toolbar=true is added, all toolbars will be loaded (top, side panel and bottom status)

Query parameters for application initialization

External and Internal Domains and Object Identification

The discussed API was designed to work both on HDC internal ID  and external domain ID. 

For more information, see 

• External Information Domains

• FI2 data import

When data is imported or otherwise synchronized, external system can use GUID and object class known to it. 

Lets take a look at a Rum object imported from IFC:Image Removed

Image Added

This object, as any other object would get it's HyperDoc ID (can be named differently or hidden depending on configuration).

The second field that is interesting to us is GUID. This field is indicated in a domain (EID) that we will use for this demo:Image Removed

Image Added

We will also need Domain ID that can be discovered on the main EID screen listing all domains:

The domain ID that we will use is 505

 Why do I need to know domain ID? 

Domains are used to identify different data sources. It can be any source or system, independently from data exchange format. By providing domain ID we indicate a "profile" that describes mapping of metadata fields, 

fields used for identification, layer mapping etc. By indicating your domain ID, HDC will know what field names and what ID's does your system understand. In this way we can talk to many systems that understand different formats, field names or GUIDS that describe the same objects. Image Removed

Image Added

Another thing to note is how to identify HDC classes and their ID's. That can be done in an administrative panel, under Configuration → Object Classes

The internal Class ID for Rum is 108Image Removed

Image Added

API Methods

Using: showObject

To show the same Rum object we can use two equivalent calls:

/** * @method showObject Load given object view using InfoScope functionality.

* This will not work for content objects (documents)

* @param {objectId} * (required) HDID or TOBIS ID

* @param {classId} * (required)classId or class name from given domain

* @param {domain} * (optional) if provided, objectId is taken from TOBIS for * this domain */

showObject: function(objectId, classId, domain)

Call made with HDID (internal) and HDC Class: (see below API Methods for HD.EmbeddedApi.showObject function signature)

HD.EmbeddedApi.showObject('58307', '108');

This API will also accept Domain ID. In that case a call will be much simpler for external system, that does not know HDC class ID or internal object ID:

HD.EmbeddedApi.showObject('fe47162f-f8ee-4bed-8c4d-e30e1c5b25bf', 'fi2space', '505');

Parameters passed include GUID, class name according to your domain, and a domain ID. HDC will now translate this, using your domain profile into HDC object ID and class, and show the appropriate drawing. 

the result will be a loaded drawing with our requested object marked and selected:Image Removed

Image Added

 If the object does not have a spot representation, HDC will try to locate a default object (document) with similar rules as with HOPA "Document For Object" call. 

HOPA perspective set in System Settings will be used to locate a default link (in most cases - a perspective that looks for linked documents)

Using: Show Object By GUID

Works the same way as “Show Object” but requires only MasterGUID for object.

HD.EmbeddedApi.showObjectByGuid('0d97508f-8d5c-470c-b337-e7acc5a6602b');

View Preference can be used as last argument:tr

HD.EmbeddedApi.showObjectByGuid('0d97508f-8d5c-470c-b337-e7acc5a6602b', viewPreference);

Using: Show Multi Object

Function: HD.EmbeddedApi.showMultiObject(gridObject, viewerObject, domain, viewPreference);

 Grid Object or Viewer Object must be provided in the following form:

{
	objectId: 123,
	classId: 456
}

When domain ID is used, classId can also be your external class name.

Possible use cases for showMultiObject:

HD.EmbeddedApi.showMultiObject(null, {objectId:'6993874f-d13b-47be-a281-cfee3af58ace' , classId:'fi2space'}, 523, {autoSyncGrid: true, syncPreference: 'object'});

HD.EmbeddedApi.showMultiObject({objectId:'c3e1192e-57cf-4ecf-a857-e77b6ed98524' , classId:'fi2floor'}, {objectId:'6993874f-d13b-47be-a281-cfee3af58ace' , classId:'fi2space'}, 523);

HD.EmbeddedApi.showMultiObject({objectId:'c3e1192e-57cf-4ecf-a857-e77b6ed98524' , classId:'fi2floor'}, null, 523);

Using: Clear View

Clear View

HD.EmbeddedApi.clearView();

Function used to clear the viewer content on demand. 

Using: 3D View Preference parameter

'2D' or '3D' Parameter can be added to calls to indicate preferred view. Please note, that when the 3D view is not available for this object, it will not fall back to 2D automatically.

This parameter is optional and will only accept these two values. If it is not given or something else is passed, it will fallback to '2D' standard mode.  

Sample:

HD.EmbededApi.showObject('47854', '130', null, '3D')

Events supported in 3D mode:

• ui.docview.document.load - when the model is fully loaded and rendered. 

• ui.docview.document.ready

• ui.model.user.spot.select - when the object is selected in the model.

Spot selected event for 3D model will result in the following payload:Image Removed

Image Added

External ID (or Entity ID) is the ID used by data provider (like Ocean server) to identify objects in the 3D Viewer domain. In this case this is a Revit GUID (UUID). It might be used directly or HDC classId and objectId can be used for conversion to any other domain. 

 Note: the 3D view is obtained on different rules then a standard HDC style view. For every given object a corresponding "level" must be identified. This is achieved by data query based on perspective. In that case we are not talking about a Drawing that has a spot on it, but rather objects grouped by Level. This group should contain out object (e.g. a Door, Window or Space). If a Building is given, then all Levels (Floors) will be used to load a full model. 

Controlling zoom behavior

Standard API call has the following parameters:

HD.EmbeddedApi.showObject(<objectId>, <objectClass>, <domain>, <viewPreference>)

Now the last parameter can be either one of these:

• 2D - use standard view

• 3D - use 3D view if 3D viewing is configured

• PC - use Point Cloud view when external system with this capability is configured. Note - this view will require proper object coordinates to be present in the system. 

Or it can be an Object with additional parameters:

Parameter	possible values
mode	"2D" "3D" "PC" Default value: 2D
fitMode	0 → Zoom and Pan to view 1 → Pan only (move into view center) Default value: 0

Note: when Pan only mode is used, and object might not fit into view. Zoom will not be changed to accommodate new shape.
fitMargin	Fit margin given as values between 0.1 (corresponds to 10%) and 5.0 (corresponds to 500%) If this parameter is not given a user parameter or system parameter is used. Only applicable when fitMode "0" is used. Default value is 50% margin.

Sample objects:

HD.EmbeddedApi.showObject(1234, 8, 512, "2D"); 
HD.EmbeddedApi.showObject(1234, 8, null, {mode: "2D", fitMode: 0, fitMargin: 0.8});
 HD.EmbeddedApi.showObject(1234, 8, 512, {mode: "2D", fitMode: 1});

Using: getSelectedObjects

/** * @method {getSelectedObjects}

Get array of selected objects For each* selected spot, find linked object and return it's ID.

* @param {domain} * domain that should be used to identify class ID. If domain

* is not given, the result is returned immediately but will * contain HD ID's. If Domain is specified, result must be

* returned in async callback.

* @param {callback} * a callback function that will be called when ID's are converted to specified domain

* @param {context} * a callback function context

*/

getSelectedObjects: function(domainId, callback, context)

Using this function will return ID and class information for all selected objects. It's important to know, that we actually select vector element that can be linked to many objects. It's not always simple 1:1 link. 

The simples version of this call does not require any arguments:

HD.EmbeddedApi.getSelectedObjects();

With the above call we will get HDID + HDC Class that might not be suitable for external system. To change that, we need to provide additional parameters. In this case: domain ID: '505' and a callback function.

Call back function is needed, because the client viewer does not have full metadata information about selected objects. Based on given domain ID, we will make an asynchronous call to server for proper metadata. 

When the conversion is done, function will be called with provided context and object data as a first argument. 

HD.EmbeddedApi.getSelectedObjects('505', function(success, data){console.log(success, data)}, this);

Observe the success parameter. Data parameter will only contain objects information when success equals true. The returned data should have the following form:

{
    "objects": [{
        "objectId": "58322",
        "classId": "108",
        "externalId": "92f62113-ec34-44ef-bb65-1d6abf0a1059",
        "tobisFieldname": "fi2space_guid",
        "externalClassName": "fi2space"
    }, {
        "objectId": "58321",
        "classId": "108",
        "externalId": "911dd976-e34c-46b5-92c7-dc5a7d13904b",
        "tobisFieldname": "fi2space_guid",
        "externalClassName": "fi2space"
    }, {
        "objectId": "58307",
        "classId": "108",
        "externalId": "fe47162f-f8ee-4bed-8c4d-e30e1c5b25bf",
        "tobisFieldname": "fi2space_guid",
        "externalClassName": "fi2space"
    }]
}

From the external system point of view, the following parameters are interesting:

1. externalId: external ID, can be GUID or other indicated field

2. tobisFieldname: name of the field indicated as ID in external domain

3. externalClassname: class name as translated to indicated domain

If eidId is empty, it means that the selected object was found, but it does not contain this property. 

Using: getSelectionMetrics

This method can be used to get area and length summary of selected elements on the drawing. 

Several important remarks:

If viewer is in InfoScope mode (e.g not showing Document, but loaded with Room or Rental Unit context) selection will work for an Object, not drawing element.

That means ALL spots linked to this object will be selected automatically and the resulting area will be summarized.

If we have a database with three layers BRA, NTA and BTA spots from all layers will be taken into account. That might change when default link for spot is introduced, or area might be separated on per layer basis (not available today). Image Removed

Image Added

Using: applyFilter

This method can be used to apply filter to drawing. A filter ID must be known. 

 This call should be used in headless mode as it will not synchronize the filter selection dropdown. A legend will be shown if side panel is available. 

See Ad-hoc External Filters for custom filters.

Embedded API through Window.postMessage()

See Integration with 3rd party websites for more details.

Show Object - Object resolution logic

Show object is using a specific logic to resolve what should be shown in the viewer, based on passed object ID.

The passed object ID can be one of these:

1. Object with content (Document ID)

2. Object with attachment

3. Object with spot on one of the documents

4. Object with default document link

5. Object without a default link, but with one or more documents linked according to HOPA perspective

The logic can be summarized as follows:

1. if the object has "external" content, load this content

2. If the object has internal content (it's a document) or if it has a connected attachment, load it into view

3. If the object does not have any content, start the so called InfoScope mode:

   1. try to find content for object by linked spot (e.g. room) or indirectly using Viewer perspective (e.g. Rental Unit)

   2. if there are multiple content objects found, load first one and allow navigation between further elements (requires toolbar to be active)

   3. If no content was found, check if default link is set to a document

   4. If there is no default link to a document

      1. get links to objects according to HOPA Document perspective

      2. check if there are document type objects there

         1. if there are objects there, try to find an object that matches preferred HOPA object class or related to that object class

         2. if there are no preferred object classes, try to find first document object

         3. load the found document object or quit (show blank view)