Introduction

Most filters are defined by a system administrator and are considered to be named filters. They can be automatic or static, with specific conditions and toolsets.

They have one thing in common - they all rely on data that is stored in HDC database and can be seen as metadata for objects. 

Ad-hoc External Filters are different, as they rely on data provided from an external source. 

Setting up an External Filter

Data provided must relate to an existing HDC objects, that have a specific geometrical representation.

The idea of that is to extend existing metadata for the presentation purposes only.  It can be a temporal data that changes often and there is no need to store that inside of 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:

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

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

Definition of matching tools to be used. As currently implemented, tools definition must be passed. Future implementations might allow using built in tools by ID/name or using automatic tools (random).

• name - name of the tool that will be used to match one of the given values in the object

• fillColor - fill color given in CSS compatible form (HTML colors or HEX)

• fillOpacity - fill opacity, value should be withing 0-1 range

• strokeColor - stroke color given in CSS compatible form (HTML colors or HEX)

• strokeOpacity - stroke opacity, value should be withing 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:

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

Visualising data from other system with ad hoc filter 

SINCE 3.8.0

Via API fetch data for ad hoc filter can be presented in the application (FMA fetch data from Landlord). Ad hoc filter includes filter legend and can be printed to PDF as usual. Primarily for 2D drawings. 

If there is a need such external communication can be adjusted 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
2. 
   
   
   
3. 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: