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:

For more information, refer to full API documentation

Filter payload components

Main filter definition

• 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

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:

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:

    

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.

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

2. Open

   

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:

Open