Translation needed

The content of this page was copied from another page tree and needs to be translated or updated.

When you finish translation, make sure to

Replace the label NEEDS-TRANSLATING with TRANSLATED
Remove this macro from the page

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

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:

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 (no) Forhåndsdefinerte filtre

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. 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:

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 (no) 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 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..

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:

HyperDoc (HDC) Manual

(no) Ad-hoc External Filters