1 Introduction
2 Setting up an External Filter
3 Filter payload components
- 3.1 Main filter definition
- 3.2 Objects
- 3.3 Tools
- 3.4 Full sample payload
4 Using the filter
5 Using External filters through Embedded API
6 Visualising data from other system with ad hoc filter

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

Since 2.6.0

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

Option	Default value	Description

Option	Default value	Description
showSpotArea	True	If set to True, summary column based on linked spot area is added
showCount	True	If set to True, summary column based on number of objects is added
showCustomSummary	False	If set to True, summary column based on custom value is added. The value is taken from object properties or from value passed in summaryValue in each object. This option is mutually exclusive with showSpotArea
summaryLabel	--	A label string used for custom summary column, e.g. "Area BRA"
summarySuffix	--	A custom suffix added to total value, e.g. "m2"
summaryField	--	A custom numeric field from object to be used as data source for custom summary.
layerName	--	name of the layer to which presentation will be applied to (since v. 3.8.0)

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

Since 2.6.0

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

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:

Using the filter

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

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:

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:

When the viewer is ready, setup new filter:
Function signature: setExternalFilter: function(filterData, autoApply, callback, context);
Example: HD.EmbededAp.setExternalFilter(filterData, true, null, null);
If you have selected autoApply = false, then the filter can be applied when the callback is returned.
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:

Visualising data from other system with ad hoc filter

Since 3.8.0

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.

Go to Administration->System->System Settings->Other->External Presentations
you click Add or Edit button dialog form will appear
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: