Introduction

Filters are typically defined by a system administrator and

referred to

as named filters. They can be either automatic or static, each with its own set of specific conditions and toolsets.

However, they share a commonality in that they all depend on data stored in the HDC database, serving as metadata for objects.

In contrast, Ad-hoc External Filters

differ from these filters as they

depend on data

supplied from an external source.

Setting up an External Filter

The provided data should pertain to existing HDC objects

with a specific geometrical representation.

The

purpose is to

expand the existing metadata for

presentation purposes only.

This may involve temporal data that changes

frequently and does not need to be stored within the versioned HDC database.

To setup a filter, the following service should be used with POST method:

http://localhost/api/presentation/adhoc/json

For more information, refer to full API documentation

Filter payload components

Main filter definition

"filter": {
    "title": "Room Type",
    "domain": "1234",
    "objectClass": "fi2Space"
	"showSpotArea": false, 
	"showCount": true,
	"showCustomSummary": true,
	"summaryLabel": "Area BRA",
	"summarySuffix" : "m2",
	"summaryField": "fi2space_areabra" 
}

• title- a name that will be used for that filter title

• domain - external domain, if given, object ID's are assumed to be given from that domain

• objectClass - object class that this filter should target

Using custom summary columns and values

In the filter definition a number of options regarding summary column can be used:

For more information, please refer to Predefined Filters

Objects

"objects": [{
    "value": "WC",
    "id": "123",
	"summaryValue": 50
}]

Array of objects with the following properties:

• value - an external property value that will be used to assign filter

• id - an internal or external object id

Custom summary value

If showCustomSummary  is set to true in filter definition and summaryField  is not given, value provided in summaryValue  in each object will be used.

Tools

"tools": [{
        "name": "WC",
        "fillColor": "green",
        "fillOpacity": "0.4",
        "strokeColor": "darkgreen",
        "strokeOpacity": "0.8"
    }

Definition of matching tools to be used.

The current implementation requires passing the tools definition

. However, in future implementations, it may be possible to use built-in tools by ID/name or

utilize automatic tools (random).

• name

• : Name of the tool that will be

• utilized to match one of the given values in the object.

• fillColor

• : Fill color

• provided in CSS compatible form (HTML colors or HEX).

• fillOpacity

• : Fill opacity, value should be

• within 0-1 range.

• strokeColor

• : Stroke color

• provided in CSS compatible form (HTML colors or HEX).

• strokeOpacity

• : Stroke opacity, value should be

• within 0-1 range.

Full sample payload

Full sample payload for external filter:

{
    "filter": {
        "title": "Room Type",
        "domain": "12",
        "objectClass": "HDV_H1_SPACE"
    },
    "objects": [{
        "value": "WC",
        "id": "5105701/10/1"
    }, {
        "value": "BAD",
        "id": "5105701/10/107"
    }, {
        "value": "ROOM",
        "id": "5105701/10/106"
    }, {
        "value": "ROOM",
        "id": "5105701/10/7"
    }],
    "tools": [{
        "name": "WC",
        "fillColor": "green",
        "fillOpacity": "0.4",
        "strokeColor": "darkgreen",
        "strokeOpacity": "0.8"
    }, {
        "name": "BAD",
        "fillColor": "blue",
        "fillOpacity": "0.4",
        "strokeColor": "darkblue",
        "strokeOpacity": "0.8"
    }, {
        "name": "ROOM",
        "fillColor": "blue",
        "fillOpacity": "0.4",
        "strokeColor": "darkblue",
        "strokeOpacity": "0.8"
    }]
}

Using the filter

When setting up a new ad-hoc filter, an ID will be returned by the server. 

{
	objectId : 1081122505
}

This ID can be used to apply filter in any of the data calls that take filter ID as a parameter, that includes, but is not limited to: viewer, HOPA calls, print.

Filter can be applied / cleared by the Embedded API controller:

HD.EmbededApi.applyFilter(filterId);
HD.EmbededApi.clearFilter();

For use in HOPA, see HOPAGetView4Object and Presentation ID parameter. 

Filter definition is stored in the user session.  When the session is terminated, the filter will not be available anymore. 

 If the filter is setup by another user / session it will not be available for use!

Using External filters through Embedded API

For easier session management, the ad-hoc filter can be applied directly through Embedded API in these simple steps:

1. When the viewer is ready, setup new filter:

2. Function signature: setExternalFilter: function(filterData, autoApply, callback, context);
   Example: HD.EmbededAp.setExternalFilter(filterData, true, null, null);

3. If you have selected autoApply = false, then the filter can be applied when the callback is returned.

4. Callback signature: myFunction: function(success, response)
   Response is an object containing objectId property with the ID of the newly created filter. 
   
   Sample for full call, where filter is an object with filter definition:

   Code Block
   HD.EmbededApi.setExternalFilter(filter, true, function(success, filter) { console.log(filter.objectId); }, this)

Visualising data from other system with ad hoc filter 

Via the API

, data for ad hoc

filters can be

retrieved and displayed in the application (FMA

retrieves data from Landlord). Ad hoc

filters consist of filter legends and can be printed to PDF as usual

, primarily for 2D drawings.

If

necessary, such external communication can be

adapted to other systems as well.

1. Go to Administration->System->System Settings->Other->External Presentations
   you click Add or Edit button dialog form will appear

1. Image Added

2. On the dialog you can set:
   

   • Username and Password to authenticate in external service,

   • Description - this will be used as suffix for the presentation's name in the presentation's combo,

   • External Information Domain - domain that will be used to match objects from external system and from HDC,

   • Parent Class - class of the object to which the document with the spots is connected,

   • Child Class - class of objects linked to spots,

   • Get queries URL - URL for getting list of queries,

   • Filter URL - URL for getting ad-hoc presentation from external system.

Below there are three examples of possible ways to call/fetch the information:

https://{server}/api/v2/floor/action/ExecuteQuery/{guid}?queryid={queryid}

https://{server}/api/v2/floor/action/ExecuteQuery?cadkey={cadkey}&queryid={queryid}

https://{server}/api/v2/floor/action/ExecuteQuery?cadkey={cadkey}&queryid={queryid}&calcdate=2019-01-01

Query parameters accepted by Faciliate

• "cadkey" – Common guid/key between systems

• "queryid" – ID of query from GetPossibleQueries call

• "calcdate" – optional parameter to specify calculation date, using “today” as default value if omitted.

Possible "active" fields to be used in FilterUrl:

• {GUID} - will be populated with an object ID as resolved by the external domain

• {queryId} - query / filter selected by the user

Date is not supported on HDC side. 

When properly configured, external filters will be available from HDC Presentation panel: