Filter Expression Criteria
- Each filter expression may contain one or more criteria combined by AND/OR operators and optionally grouped by parentheses.
- Each criteria may be based on property name, System Tag, or Custom Tag.
- All property names are based on data contract of the target Main API version - the client specifies only what it sees at the moment of integration and does not change later. This means that clients using Main API v201903 refer to Player Health Status property as
[HealthStatus],expecting to get one of { "NoSubscriptions", "Normal", "Warning", "Error" } enumeration values. The clients using v202010 refer to it as[Status].[Health]and the clients which will use some next version will refer to it at some different path and will expect even different, more specific values and all of that must be supported at the same time based on the same internal dataset. It means that regardless of the target Main and Device API versions used by customers and Players for reporting Player Settings and Status this information must be available for retrieval and handle expressions of all existing formats in all Main and Device API versions at the same time.
According to initial business requirements the Main API must support filtering and sorting by all properties exposed in its data contracts. But due to syntax specifics the list of supported 'Player' Entity properties is currently limited to:
In v201903 and v202007
As defined in 'BSN.WebServices.Main.v201903.DTO.Device', 'BSN.WebServices.Main.v202007.DTO.Device' and referenced classes:[Id] // integer
[Serial] // string
[Name] // string
[ConcatUnitNameAndSerial] // boolean
[Description] // string
[CurrentSubscription] // object
[CurrentSubscription].[Id] // integer
[CurrentSubscription].[DeviceId] // nullable integer
[CurrentSubscription].[Type] // string-enumeration
[CurrentSubscription].[ActivityPeriod] // TimeSpan
[CurrentSubscription].[Status] // string-enumeration
[CurrentSubscription].[CreationDate] // DateTime
[CurrentSubscription].[ActivationDate] // nullable DateTime
[CurrentSubscription].[SuspensionDate] // nullable DateTime
[CurrentSubscription].[ExpirationDate] // nullable DateTime
[TargetGroup] // object
[TargetGroup].[Id] // integer
[TargetGroup].[Name] // string
[TaggedGroups] // object array
[TargetBrightWall] // object
[TargetBrightWall].[Id] // integer
[TargetBrightWall].[Name] // string
[TargetBrightWallScreenNumber] // nullable byte
[ReportedGroup] // object
[ReportedGroup].[Id] // integer
[ReportedGroup].[Name] // string
[ReportedBrightWall] // object
[ReportedBrightWall].[Id] // integer
[ReportedBrightWall].[Name] // string
[ReportedBrightWallScreenNumber] // nullable byte
[Presentation] // object
[Presentation].[Id] // integer
[Presentation].[Name] // string
[Model] // string-enumeration
[Family] // string-enumeration
[RegistrationDate] // DateTime
[LastModifiedDate] // DateTime
[Autorun] // object
[Autorun].[Version] // string
[Autorun].[IsCustom] // boolean
[FirmwareVersion] // string
[CardSize] // string
[CardFreeSize] // string
[TargetTimeZone] // string
[ReportedTimeZone] // string
[ExternalIpAddress] // string
[ScreenColor] // string
[SetupType] // string-enumeration
[ContentCheckPeriod] // string-enumeration
[ContentDownloadsStartTime] // nullable TimeSpan
[ContentDownloadsEndTime] // nullable TimeSpan
[HealthReportingPeriod] // string-enumeration
[HealthReportingStartTime] // nullable TimeSpan
[HealthReportingEndTime] // nullable TimeSpan
[LastContentCheckTime] // DateTime
[LastSyncSpecProcessedTime] // DateTime
[LastContentDownloadStartTime] // DateTime
[LastContentDownloadEndTime] // DateTime
[LastHeartbeatTime] // DateTime
[LastErrorTime] // DateTime
[Uptime] // TimeSpan
[HealthStatus] // string-enumeration
[NetworkSettings] // object
[NetworkSettings].[Hostname] // string
[NetworkSettings].[ProxyServer] // string
[NetworkSettings].[ProxyBypass] // string array
[NetworkSettings].[TimeServer] // string
[NetworkSettings].[WiredConnectionPriority] // integer
[NetworkSettings].[WirelessConnectionPriority] // integer
[NetworkSettings].[Wired] // object
[NetworkSettings].[Wired].[UseDHCP] // boolean
[NetworkSettings].[Wired].[IpAddress] // string
[NetworkSettings].[Wired].[SubnetMask] // string
[NetworkSettings].[Wired].[DefaultGateway] // string
[NetworkSettings].[Wired].[DNS1] // string
[NetworkSettings].[Wired].[DNS2] // string
[NetworkSettings].[Wired].[DNS3] // string
[NetworkSettings].[Wired].[RateLimitInsideContentDownloadWindow] // nullable unsigned integer
[NetworkSettings].[Wired].[RateLimitOutsideContentDownloadWindow] // nullable unsigned integer
[NetworkSettings].[Wired].[RateLimitDuringInitialDownloads] // nullable unsigned integer
[NetworkSettings].[Wired].[ContentDownloadEnabled] // boolean
[NetworkSettings].[Wired].[TextFeedsDownloadEnabled] // boolean
[NetworkSettings].[Wired].[MediaFeedsDownloadEnabled] // boolean
[NetworkSettings].[Wired].[HealthReportingEnabled] // boolean
[NetworkSettings].[Wired].[LogsUploadEnabled] // boolean
[NetworkSettings].[Wireless] // object
[NetworkSettings].[Wireless].[Enabled] // boolean
[NetworkSettings].[Wireless].[SSID] // string
[NetworkSettings].[Wireless].[Passphrase] // string
[NetworkSettings].[Wireless].[UseDHCP] // boolean
[NetworkSettings].[Wireless].[IpAddress] // string
[NetworkSettings].[Wireless].[SubnetMask] // string
[NetworkSettings].[Wireless].[DefaultGateway] // string
[NetworkSettings].[Wireless].[DNS1] // string
[NetworkSettings].[Wireless].[DNS2] // string
[NetworkSettings].[Wireless].[DNS3] // string
[NetworkSettings].[Wireless].[RateLimitInsideContentDownloadWindow] // nullable unsigned integer
[NetworkSettings].[Wireless].[RateLimitOutsideContentDownloadWindow] // nullable unsigned integer
[NetworkSettings].[Wireless].[RateLimitDuringInitialDownloads] // nullable unsigned integer
[NetworkSettings].[Wireless].[ContentDownloadEnabled] // boolean
[NetworkSettings].[Wireless].[TextFeedsDownloadEnabled] // boolean
[NetworkSettings].[Wireless].[MediaFeedsDownloadEnabled] // boolean
[NetworkSettings].[Wireless].[HealthReportingEnabled] // boolean
[NetworkSettings].[Wireless].[LogsUploadEnabled] // boolean
[RemoteSnapshotSettings] // object
[RemoteSnapshotSettings].[Enabled] // boolean
[RemoteSnapshotSettings].[CaptureInterval] // TimeSpan
[RemoteSnapshotSettings].[ScreenShotsCountLimit] // unsigned short
[RemoteSnapshotSettings].[ImageQuality] // byte
[RemoteSnapshotSettings].[ScreenOrientation] // string-enumeration
[LogsSettings] // object
[LogsSettings].[EnableDiagnosticLog] // boolean
[LogsSettings].[EnableEventLog] // boolean
[LogsSettings].[EnablePlaybackLog] // boolean
[LogsSettings].[EnableStateLog] // boolean
[LogsSettings].[EnableVariableLog] // boolean
[LogsSettings].[UploadAtBoot] // boolean
[LogsSettings].[UploadTime] // nullable TimeSpan
[DiagnosticWebServerSettings] // object
[DiagnosticWebServerSettings].[Enabled] // boolean
[DiagnosticWebServerSettings].[Password] // string
[LocalWebServerSettings] // object
[LocalWebServerSettings].[Enabled] // boolean
[LocalWebServerSettings].[UserName] // string
[LocalWebServerSettings].[Password] // string
[LocalWebServerSettings].[EnableUpdateNotifications] // boolean
[DeviceLocation] // object
[DeviceLocation].[PlaceId] // string
[DeviceLocation].[GPSLatitude] // nullable double
[DeviceLocation].[GPSLongitude] // nullable double
[DeviceLocation].[Country] // string
[DeviceLocation].[CountryLongName] // string
[DeviceLocation].[AdminAreaLevel1] // string
[DeviceLocation].[AdminAreaLevel1LongName] // string
[DeviceLocation].[AdminAreaLevel2] // string
[DeviceLocation].[AdminAreaLevel2LongName] // string
[DeviceLocation].[Locality] // string
[DeviceLocation].[LocalityLongName] // string
[DeviceLocation].[Path] // string
[DeviceLocation].[PathLongName] // string
[ForceReboot] // boolean
[ForceRecovery] // boolean
[ForceReformat] // boolean
[ForceLogUpload] // boolean
[Beacons] // object array
[Tags] // object
[Permissions] // object arrayIn v202010
AsFilter Expression Criteria
- Each filter expression may contain one or more criteria combined by AND/OR operators and optionally grouped by parentheses.
- Each criteria may be based on property name, system tag, or custom tag.
- All property names are based on data contract of the target Main API version - the client specifies only what it sees at the moment of integration and does not change later. This means that clients using Main API v202010 refer to the Player Health Status property as
[Status].[Health],expecting to get one of { "NoSubscriptions", "Normal", "Warning", "Error" } enumeration values. C
According to initial business requirements the Main API must support filtering and sorting by all properties exposed in its data contracts. But due to syntax specifics the list of supported 'Player' entity properties in v2020/10 is currently limited to the following, as defined in 'BSN.WebServices.Main.v202010.DTO.Device' and referenced classes:
[Id] // integer
[Serial] // string
[Model] // string-enumeration
[Family] // string-enumeration
[RegistrationDate] // DateTime
[LastModifiedDate] // DateTime
[Settings] // object
[Settings].[Name] // string
[Settings].[Description] // string
[Settings].[ConcatUnitNameAndSerial] // boolean
[Settings].[SetupType] // string-enumeration
[Settings].[Group] // object
[Settings].[Group].[Id] // integer
[Settings].[Group].[Name] // string
[Settings].[BrightWall] // object
[Settings].[BrightWall].[Id] // integer
[Settings].[BrightWall].[Name] // string
[Settings].[BrightWall].[Screen] // byte
[Settings].[Timezone] // string
[Settings].[Screen] // object
[Settings].[Screen].[IdleColor] // string
[Settings].[Screen].[SplashUrl] // string-URL
[Settings].[Synchronization].[Status] // object
[Settings].[Synchronization].[Status].[Period] // TimeSpan
[Settings].[Synchronization].[Settings] // object
[Settings].[Synchronization].[Settings].[Period] // TimeSpan
[Settings].[Synchronization].[Schedule] // object
[Settings].[Synchronization].[Schedule].[Period] // TimeSpan
[Settings].[Synchronization].[Content] // object
[Settings].[Synchronization].[Content].[Start] // nullable TimeSpan
[Settings].[Synchronization].[Content].[End] // nullable TimeSpan
[Settings].[Network] // object
[Settings].[Network].[Hostname] // string
[Settings].[Network].[ProxyServer] // string
[Settings].[Network].[ProxyBypass] // string array
[Settings].[Network].[TimeServers] // string array
[Settings].[Network].[Interfaces] // object array
[Settings].[Beacons] // object array
[Settings].[Location] // object
[Settings].[Location].[PlaceId] // string
[Settings].[Location].[GPSLatitude] // nullable double
[Settings].[Location].[GPSLongitude] // nullable double
[Settings].[Location].[Country] // string
[Settings].[Location].[CountryLongName] // string
[Settings].[Location].[AdminAreaLevel1] // string
[Settings].[Location].[AdminAreaLevel1LongName] // string
[Settings].[Location].[AdminAreaLevel2] // string
[Settings].[Location].[AdminAreaLevel2LongName] // string
[Settings].[Location].[Locality] // string
[Settings].[Location].[LocalityLongName] // string
[Settings].[Location].[Path] // string
[Settings].[Location].[PathLongName] // string
[Settings].[Screenshots] // object
[Settings].[Screenshots].[Interval] // TimeSpan
[Settings].[Screenshots].[CountLimit] // unsigned short
[Settings].[Screenshots].[Quality] // byte
[Settings].[Screenshots].[Orientation] // string-enumeration
[Settings].[Logging] // object
[Settings].[Logging].[EnableDiagnosticLog] // boolean
[Settings].[Logging].[EnableEventLog] // boolean
[Settings].[Logging].[EnablePlaybackLog] // boolean
[Settings].[Logging].[EnableStateLog] // boolean
[Settings].[Logging].[EnableVariableLog] // boolean
[Settings].[Logging].[UploadAtBoot] // boolean
[Settings].[Logging].[UploadTime] // nullable TimeSpan
[Settings].[LWS] // object
[Settings].[LWS].[UserName] // string
[Settings].[LWS].[Password] // string
[Settings].[LWS].[EnableUpdateNotifications] // boolean
[Settings].[LDWS] // object
[Settings].[LDWS].[Password] // string
[Settings].[LastModifiedDate] // DateTime
[Status] // object
[Status].[Group] // object
[Status].[Group].[Id] // integer
[Status].[Group].[Name] // string
[Status].[BrightWall] // object
[Status].[BrightWall].[Id] // integer
[Status].[BrightWall].[Name] // string
[Status].[BrightWall].[Screen] // byte
[Status].[Presentation] // object
[Status].[Presentation].[Id] // integer
[Status].[Presentation].[Name] // string
[Status].[Presentation].[Type] // string-enumeration
[Status].[Timezone] // string
[Status].[Synchronization] // object
[Status].[Synchronization].[Settings] // object
[Status].[Synchronization].[Settings].[Enabled] // boolean
[Status].[Synchronization].[Schedule] // object
[Status].[Synchronization].[Schedule].[Enabled] // boolean
[Status].[Synchronization].[Content] // object
[Status].[Synchronization].[Content].[Enabled] // boolean
[Status].[Script] // object
[Status].[Script].[Type] // string-enumeration
[Status].[Script].[Version] // string
[Status].[Script].[Plugins] // object array
[Status].[Firmware] // object
[Status].[Firmware].[Version] // string
[Status].[Storage] // object array
[Status].[Network] // object
[Status].[Network].[ExternalIp] // string
[Status].[Network].[Interfaces] // object array
[Status].[Uptime] // TimeSpan
[Status].[CurrentSettingsTimestamp] // DateTime
[Status].[CurrentScheduleTimestamp] // DateTime
[Status].[Health] // string-enumeration
[Status].[LastModifiedDate] // DateTime
[Subscription] // object
[Subscription].[Id] // integer
[Subscription].[Device] // object
[Subscription].[Device].[Id] // nullable integer
[Subscription].[Device].[Serial] // string
[Subscription].[Type] // string-enumeration
[Subscription].[ActivityPeriod] // TimeSpan
[Subscription].[Status] // string-enumeration
[Subscription].[CreationDate] // DateTime
[Subscription].[ActivationDate] // nullable DateTime
[Subscription].[SuspensionDate] // nullable DateTime
[Subscription].[ExpirationDate] // nullable DateTime
[TaggedGroups] // object array
[Tags] // object
[Permissions] // object arraySystem and Custom Tags
In addition to Properties properties each 'Player' Entity entity instance may have a different set of System system and Custom Tags custom tags specified by customer, exposed via 'the [Dictionary<string, object>] Tags' property property and managed via the following BSN.cloud Main API methods:
PUT ~/{version}/REST/Devices/{playerId:int}/
PUT ~/{version}/REST/Devices/{serial}/
PATCH ~/{version}/REST/Devices/{playerId:int}/
PATCH ~/{version}/REST/Devices/{serial}/
GET ~/{version}/REST/Devices/{playerId:int}/Tags/
GET ~/{version}/REST/Devices/{serial}/Tags/
POST ~/{version}/REST/Devices/{playerId:int}/Tags/
POST ~/{version}/REST/Devices/{serial}/Tags/
DELETE ~/{version}/REST/Devices/{playerId:int}/Tags/
DELETE ~/{version}/REST/Devices/{serial}/Tags/Each System system and Custom Tag custom tag must be explicitly specified for the target Entity entity instance but the list of available System Tags system tags is pre-defined by product owners and mapped to some properties so their values must be always in sync. For example, the System Tag system tag mapped to Player Health Status the player health status property is called
string::[Device].<HealthStatus>Technically this is implemented in [dbo].[GetSystemTagValue] MS SQL user-defined function which calculates all System Tag system tag values - there you can find the list of all currently supported System Tagssystem tags.
Property and Tag Mentions in Expressions
Property and Tag tag mentions in expressions are different: properties are wrapped by square brackets each and are separated by dots while Tags tags are wrapped by angle brackets and may optionally be prepended by the target Entity Name entity name in square brackets, and the data type is separated by double colon as you can see in the example above. Each property and Tag tag has a strong data type, for properties and System Tags system tags it is defined in data contract of a target API version and for Custom Tags - custom tags it is resolved either from fully qualified name or first assigned value. In addition to that , there is a request to support Custom Tags custom tags without values acting as labels. The data type defines which operators and functions are applicable to a given property or Tag tag in conditions.
The properties and Tags tags of boolean data type typically support the following operators:
IS TRUE
IS FALSEThe properties and Tags tags of numeric data types typically support the following operators:
IS {number}
IS NOT {number}
IS GREATER THAN {number}
IS LESS THAN {number}
IS IN THE RANGE {number} AND {number}
IS NOT IN THE RANGE {number} AND {number}
IS IN ({number}, {number}, ...)
IS NOT IN ({number}, {number}, ...)plus the GPS coordinates also support expressions like
GPS LOCATION ([Latitude] AND [Longitude]) IN ({latitude}, {longitude}, {distance})
GPS LOCATION ([Latitude] AND [Longitude]) NOT IN ({latitude}, {longitude}, {distance})The properties and Tags tags of string data type typically support the following operators:
IS NULL
IS NOT NULL
IS '{expression}'
IS NOT '{expression}'
BEGINS WITH '{string}'
ENDS WITH '{string}'
CONTAINS '{string}'
DOES NOT CONTAIN '{string}'
CONTAINS ALL ('{string}', '{string}', ...)
CONTAINS ANY ('{string}', '{string}', ...)
IS IN ('{string}', '{string}', ...)
IS NOT IN ('{string}', '{string}', ...)The expressions used in IS and IS NOT operators may include '*', '?', '[' + ']' wildcards.
The properties and Tags tags of DateTime (timestamp) data type typically support the following operators:
IS '{DateTime}'
IS NOT '{DateTime}'
IS AFTER '{DateTime}'
IS BEFORE '{DateTime}'
IN THE LAST ({interval}, {range}, '{DateTime}') where {interval} is one of { "YEARS", "MONTHS", "DAYS" } enumeration values
NOT IN THE LAST ({interval}, {range}, '{DateTime}') where {interval} is one of { "YEARS", "MONTHS", "DAYS" } enumeration values
IS IN THE RANGE '{DateTime}' AND '{DateTime}'
IS NOT IN THE RANGE '{DateTime}' AND '{DateTime}'
IS IN ('{DateTime}', '{DateTime}')
IS NOT IN ('{DateTime}', '{DateTime}')The '{DateTime}' value format must follow ISO 8601 and is typically like '2021-12-20T18:25:01.123Z'.
The properties and Tags tags of TimeSpan (time interval) data type typically support the following operators:
IS '{TimeSpan}'
IS NOT '{TimeSpan}'
IS GREATER THAN '{TimeSpan}'
IS LESS THAN '{TimeSpan}'
IS IN ('{TimeSpan}', '{TimeSpan}')
IS NOT IN ('{TimeSpan}', '{TimeSpan}')The '{TimeSpan}' value format must follow ISO 8601 and is typically like '3.18:25:01'.
The properties and Tags tags of numeric array data types typically support the following operators:
IS NULL
IS NOT NULL
CONTAINS ALL ('{number}', '{number}', ...)
CONTAINS ANY ('{number}', '{number}', ...)The properties and Tags tags of string array data type typically support the following operators:
IS NULL
IS NOT NULL
CONTAINS ALL ('{string}', '{string}', ...)
CONTAINS ANY ('{string}', '{string}', ...)The properties and Tags tags of object data type typically support the following operators:
IS NULL
IS NOT NULLSort expressions may contain only one fully qualified property name or Tag tag with optional ASC/DESC qualifier but should support more in future.