How to use Device and Software search

In Applixure web UI, you can use search functionality with Agents (devices) and Software objects to filter and list your assets in the list view. In similar fashion, graphs and lists of alerts and warnings in the Applixure web UI's main views (Devices, Software, Issues and Use) use the exact same search queries to filter the mosaic and display results in the list view. 

 

You can enter into Devices search view either through the "Show devices as list" link in the Devices main view, under assets' mosaic display: 

 

devices-show-as-list.png

 

 

Or from the submenu underneath the Devices -view link on the left-hand side navigation menu: 

 

devices-search-link.png

 

Similarly, search for software assets can be found from the Software main view and/or from the submenu entry in the navigation menu. 

 

Once in the list view, if no specific search terms or queries are entered all the available agents or software assets are shown by default, depending on the chosen list view. 

 

search-screen.png

 

However, if you had clicked on some specific graph in the main view - filtering the assets - and then selected "Show as list" underneath the mosaic, you would automatically be shown the filtered list of assets in this screen as well with the currently active search query visible in the text box on top of the page. 

 

In this view, you can now modify the search query text and press enter or click on the magnifying glass icon to update the list of assets matching the search terms in that query. 

 

Objects and fields 

 

To have an unified experience, search functionality in Applixure uses the exact same field names for asset objects as in the data that can be had on an environment -basis through our Connect API in JSON format. You can find the up-to-date technical specification document for all objects in the public API here, but for your convenience we have listed the most common field name also at the end of this document. In the spec file, you will need to look for object specification for AgentDataCurrent for agent/device objects and ProductGroupDataCurrent for software objects. 

 

When searching for devices or software assets, the fully-qualified path to fields are as follows: 

 

Object type Prefix + field name
Agents agent.<field>[.<field>]
Software software.<field>[.<field>]

 

As some of the fields in objects are actually in nested sub-objects (like, for instance, security readiness -related fields in agent -object), you may need to reference the path to those fields using notation where separating path components using dot (.) until the ultimate field name being searched against is the last component given. 

 

For your convenience, when searching for agents/devices in the devices search, you may omit the "agent." prefix of the path and only reference the actual field names and in the same manner in software search, omit the "software." prefix. However, in the software search since the search will be extended to inside the linked product versions from the software object (representing product group level - please see the explanation of the software asset model in Applixure from our Connect API documentation), you may need to use explicit "software." prefix to disambiguate which object type is being searched for as both the software object and the individual product version object has fields with identical names - such as "Name". 

 

In the data, some of the fields may reference an array of sub-objects - for instance in the agent data there might be zero, one or multiple displays as part of the agent device's configuration. In the search syntax, you can use the name of the array field as-is and the search will be performed against all of the sub-objects automatically. As an example, the displays mentioned above could be searched by: 

 

displays.name = "Generic" 

 

This would list all agents having at least one display attached which has the word "Generic" in the name -field. 

 

Linked objects 

 

As mentioned above, both agent and software objects can also contain references to other object types as part of their object graph which in the API's JSON data are given as object ID references only. Applixure search currently supports some of these linked references through automatically resolving the linkages using the object ID and substituting it with contents of the actual linked object, allowing search to "reach in" to these nested objects. 

 

As an example, agent and software objects can have reference to tags associated with them through the "LinkedTags" field. In the search, these linked tags can be queried just as they would be part of the base object's normal internal sub-objects, such as: 

 

linkedtags.value = "My tag" 

 

or specifying the tag type's name along with the tag's value itself (performing two-level nested search from the agent object): 

 

linkedtags.value = "My tag" and linkedtags.tagtypeid.name = "My tagtype" 

 

Example of searching for agent objects 

 

Given that one of the agent objects in our environment is defined like the following when read from the JSON data in the public API: 

 

{
      "AgentId": "00ecca05-8d70-54ce-b774-cfbb1dc32543",
      "Batteries": [
        {
          "EstimatedRuntime": 296,
          "Manufacturer": "Hewlett-Packard",
          "MaxChargeCapacity": 100,
          "Name": "Primary",
          "SerialNumber": "70826795"
        }
      ],
      "Components": {},
      "Country": "Finland",
      "DeviceManufacturer": "HP",
      "DeviceModel": "HP EliteBook 820 G4",
      "DeviceModelSku": "Z2V91EA#AK8",
      "DeviceScore": 4.6,
      "DeviceSerial": "",
      "DisplayCount": 1,
      "Displays": [
        {
          "Manufacturer": "DO NOT USE - AUO",
          "Name": "Generic PnP Monitor",
          "SizeInInches": "12,5"
        }
      ],
      "DnsDomain": "",
      "EnvironmentId": "7b884896-f8e9-4372-85f2-de75ad8d71d1",
      "FirmwareType": "UEFI",
      "FirmwareVersion": "P78 Ver. 01.15",
      "FirstSeen": "2018-05-17",
      "HarddiskFreeInGb": 74.6,
      "HarddiskInGb": 237.6,
      "Harddisks": [
        {
          "FirmwareVersion": "AAHA4102",
          "Model": "KXG50ZNV256G TOSHIBA",
          "SerialNumber": "70826795"
        }
      ],
      "HarddiskSystemFreeInGb": 74.6,
      "HarddiskSystemInGb": 237.6,
      "HardwareType": "Laptop",
      "Hostname": "Device-c7cbe",
      "LastSeen": "2019-07-09T21:00:48.46657Z",
      "LinkedTags": [
        "dfcfbdf2-5250-476a-ba3f-8b318683e06a"
      ],
      "LogonTime": 4,
      "LogonTimeChangePercentageIn6Months": -86,
      "MemoryInMb": 8071,
      "OperatingSystem": "Windows",
      "OperatingSystemBootTime": "2019-07-02T05:49:14.491864Z",
      "OperatingSystemInstallDate": "2017-06-26",
      "OperatingSystemName": "Microsoft Windows 10 Enterprise",
      "OperatingSystemServicing": {
        "Branch": "W10-SemiAnnualTargeted",
        "Build": 15063,
        "IsLongTermServicingVersion": false,
        "Release": "1703",
        "Revision": 1868
      },
      "OperatingSystemType": "Workstation",
      "OperatingSystemUpgradeDate": "2018-05-17",
      "OperatingSystemVersion": "10.0.15063.1868",
      "OperatingSystemVersionName": "Windows 10",
      "PowerUsage": {},
      "ProcessorArchitecture": "X64",
      "ProcessorCoreCount": 2,
      "ProcessorLogicalCount": 4,
      "ProcessorName": "Intel Core i5-7200U CPU",
      "ProcessorSocketCount": 1,
      "ProcessorSpeedInGHz": 2.7,
      "SecurityState": {
        "ActiveAntispywareNames": [
          "Computer Protection by F-Secure"
        ],
        "ActiveAntivirusNames": [
          "Computer Protection by F-Secure"
        ],
        "AntispywareOverallStatus": "Good",
        "AntivirusOverallStatus": "Good",
        "AnyDomainAccountsDirectlyInAdminGroup": false,
        "AutoupdatesInstalled": "2019-03-07T06:43:54",
        "AutoupdateStatus": "Good",
        "ExtraLocalUserAccountsInAdminGroup": true,
        "FirewallOverallStatus": "Good",
        "IsBitLockerInUse": true,
        "IsDefaultEncryptionInUseForSystemDisk": true,
        "IsDefaultEncryptionSupportedByOs": true,
        "IsIOMMUAvailable": false,
        "IsLastLogonUserLocalAdministrator": false,
        "IsLocalAdministratorEnabled": true,
        "IsOsUnderCentralManagement": true,
        "IsPricipalLogonUserLocalAdministrator": false,
        "IsSecureBootCapable": true,
        "IsSecureBootEnabled": true,
        "IsSecureFirmwareTypeInUse": true,
        "IsTpmChipAvailable": true,
        "IsTpmChipInUse": true,
        "OsCentralManagementType": "ActiveDirectory",
        "OsCentralManagementTypes": [
          {
            "Name": "Domain",
            "RealmType": "ActiveDirectory"
          }
        ],
        "OverallDeviceSecurityReadiness": "Good",
        "OverallOsSecurityReadiness": "Good",
        "OverallUserAccountSecurityReadiness": "Partial",
        "TpmChipVersion": "2.0"
      },
      "StartupTime": 38,
      "StartupTimeChangePercentageIn6Months": 90,
      "SystemManagementFirmwareVersion": "3.0"
    }

 

You could now make query to find all agents having disk encryption in use for the system disk by searching: 

 

SecurityState.IsDefaultEncryptionInUseForSystemDisk = true 

 

Or narrowing it even more by searching such devices where TPM chip version is additionally not the latest 2.0 version: 

 

SecurityState.IsDefaultEncryptionInUseForSystemDisk = true and SecurityState.TpmChipVersion is not "2.0" 

 

Or going even more specific by choosing those devices where encryption is in use but either TPM chip is of older make or secure booting is not enabled: 

 

SecurityState.IsDefaultEncryptionInUseForSystemDisk = true and (SecurityState.TpmChipVersion is not "2.0" or SecurityState.IsSecureBootEnabled = false) 

 

Given that we may have mixed OS environment, we might like to limit this search to only Windows devices: 

 

OperatingSystem = "Windows" and SecurityState.IsDefaultEncryptionInUseForSystemDisk = true and (SecurityState.TpmChipVersion is not "2.0" or SecurityState.IsSecureBootEnabled = false) 

 

Search syntax 

 

Syntax for fields and values

 

The field names must be listed on the left side of the comparison, followed by the comparison operator and finally the literal value to search on the right side (except in the case of few special comparison operators):

 

<field name> <operator> <value>

 

All field names must not be quoted with double quotes. Using double quotes around text indicates literal string and is interpreted as such by the search.

 

Search values can be of following types - these are automatically matched against the field type in the object data: 

 

Value type Remarks Example
Text string Must be double-quoted "machine123"
Integer number Must contain only digits 12345
Decimal number Must contain only digits, separated either with dot (.) or comma (,) 4.5
Boolean Must be true/false or yes/no true
Date Must be in form YYYY-MM-DD and double-quoted "2018-09-01"
Date+time Must in ISO 8601 format and double-quoted "2019-07-30T11:35:36.032362Z"
Guid Used mostly in unique IDs for objects, must be double-quoted like text strings "4df247d9-5913-58c5-963f-0a266bbd3a1d"

 

 

Scope and order of evaluation

 

The search functionality supports using all the field names in the given object type, and you can use normal logical AND and OR operators to include multiple search criterias in the query like in the examples given above.

 

By using parenthesis ( and ) you can also scope the query further, and the query is evaluated using normal left-to-right evaluation order wherein subqueries inside the parenthesis will be evaluated as its own.

 

Please make note of the evaluation order when constructing more complex queries, as the input objects against which the evaluation is performed are supplied from the left side of the query or from the upper scope (if current scope is inside the parenthesis). In concretely, this means that inside the same scope when some search term is evaluated on the left side, its output objects are already filtered based on that criteria and then only these objects will then be considered as input to the subsequent search criteria inside the same scope unless the subsequent criteria is separated by OR in which case the input objects for it comes from the parent scope.

 

A special logical operator EXCLUDE is additionally supported, which will cause removal of matching objects from the input objects to the excluded search criteria. You can use this query operator to quickly exclude some subset of objects, for example:

 

OperatingSystemVersionName = "Windows 10" exclude (OperatingSystemServicing.Branch = "W10-Current" or OperatingSystemServicing.Branch = "W10-Business")

 

Would result all Windows 10 devices which are not in the two specifed servicing rings.

 

 

Supported comparison operators

 

Following comparison operators are supported by the search for matching the field and search term:

 

Operator Meaning Remarks Applied to field type Example
 = or : or IS Equals  For text search, case-insensitive and also matches partial text All SoftwareScore = 4.0
 < Smaller than   Numbers, date, date+time SoftwareScore < 4.0
 > Larger than   Numbers, date, date+time HarddiskInGb > 100 
<= Smaller or equal than   Numbers, date, date+time LogonTime <= 10
>= Larger or equal than   Numbers, date, date+time PowerUsage.AverageTimePoweredOn >= 30
IS NOT Does not equal   All  DevicesDeployed is not 1
IS EXACTLY Equals fully

For text search, case-insensitive but contents must match exactly.

This can be used to disambiguate matches to field where search term might appear in full in one object's field and partially in another's.

Text  Attributes.Approval is exactly "Approved"
IS NOT EXACTLY Does not equal fully For text search, case-insensitive but contents must not match exactly Text Attributes.Approval is not exactly "Approved" 
IS MISSING Field is not in object data Some of the fields may be optional for object, this operator can be used to match objects where such field is not present.

With this operator, right side literal value is not used.

It is advisable to explictly use object's type in the field name to avoid doing matching to any linked sub-objects.
All agent.OperatingSystemInstallDate is missing
IS NOT MISSING Field is present in object data Some of the fields may be optional for object, this operator can be used to match objects where such field can be found.

With this operator, right side literal value is not used.

It is advisable to explictly use object's type in the field name to avoid doing matching to any linked sub-objects.
All  agent.OperatingSystemInstallDate is not missing 

 

 

 

Functions

 

In addition to normal field references in the search criterias, Applixure's search supports small number of functions that transforms data in the field to some other format.

 

Function Meaning Example
COUNT() When applied to field with array value, returns the number of elements in the array COUNT(NeverUsageAgents)
DAYS() When applied to field with date or date+time value, returns the number of days elapsed from that timestamp DAYS(FirstSeen)
MONTHS() When applied to field with date or date+time value, returns the number of months elapsed from that timestamp MONTHS(FirstSeen) 
YEARS() When applied to field with date or date+time value, returns the number of years elapsed from that timestamp YEARS(FirstSeen)

 

 

 

Short query format

 

To make it easier to search for commonly used fields, search functionality also supports using special short query format wherein you will only need to enter search term in the search field, and it will be automatically used against those common fields:

 

Search view Fields searched
Devices

Hostname
Displays.SerialNumber
LastLogonUserId.Name
LastLogonUserId.LogonName
PrincipalLogonUserId.Name
PrincipalLogonUserId.LogonName
LinkedTags.Value

Software Name
Vendor
LinkedTags.Value

 

 

 

Available fields for search

Following list of fields per object type available for searching is provided for convenience, please refer to the OAS3 specification file linked to from the developer site for most up-to-date list of fields defined for objects.

Object type Available fields
Agent

AgentId
Batteries.DegradeRate
Batteries.EstimatedRuntime
Batteries.Manufacturer
Batteries.MaxChargeCapacity
Batteries.Name
Batteries.SerialNumber
Components.Errors.DriverId
Components.Errors.ErrorCode
Components.Errors.ErrorMessage
Components.Errors.Name
Components.ThirdPartyDrivers
Country
DeviceManufacturer
DeviceManufacturerOem
DeviceModel
DeviceModelOem
DeviceModelSku
DeviceScore
DeviceSerial
DisplayCount
Displays.Manufacturer
Displays.Name
Displays.SerialNumber
Displays.SizeInInches
DnsDomain
EnvironmentId
FirmwareType
FirmwareVersion
FirstSeen
HarddiskFreeInGb
HarddiskInGb
Harddisks.FirmwareVersion
Harddisks.Model
Harddisks.SerialNumber
HarddiskSystemFreeInGb
HarddiskSystemInGb
HardwareType
Hostname
LastLogonUserId.LogonId
LastLogonUserId.Name
LastLogonUserId.FullName
LastLogonUserId.Types
LastLogonUserId.LogonName
LastSeen
LinkedTags.EnvironmentId
LinkedTags.TagId
LinkedTags.TagTypeId
LinkedTags.Value
LinkedTags.TagTypeId.Color
LinkedTags.TagTypeId.Contexts
LinkedTags.TagTypeId.EnvironmentId
LinkedTags.TagTypeId.Name
LinkedTags.TagTypeId.Tags
LinkedTags.TagTypeId.TagTypeId
LogonTime
LogonTimeChangePercentageIn6Months
LogonUtilization24HoursPercentage
LogonUtilizationPercentage
MemoryInMb
OperatingSystem
OperatingSystemBitness
OperatingSystemBootTime
OperatingSystemImageDate
OperatingSystemInstallDate
OperatingSystemName
OperatingSystemServicing.Branch
OperatingSystemServicing.Build
OperatingSystemServicing.IsLongTermServicingVersion
OperatingSystemServicing.Release
OperatingSystemServicing.Revision
OperatingSystemType
OperatingSystemUpgradeDate
OperatingSystemVersion
OperatingSystemVersionName
PowerUsage.AverageTimePoweredOn
PowerUsage.AverageTimeUseDaysPoweredOn
PowerUsage.AverageTimeWeekdaysPoweredOn
PowerUsage.TotalTimePoweredOnPastMonth
PrincipalLogonUserId.LogonId
PrincipalLogonUserId.Name
PrincipalLogonUserId.FullName
PrincipalLogonUserId.Types
PrincipalLogonUserId.LogonName
ProcessorArchitecture
ProcessorCoreCount
ProcessorLogicalCount
ProcessorName
ProcessorSocketCount
ProcessorSpeedInGHz
SecurityState.ActiveAntispywareNames
SecurityState.ActiveAntivirusNames
SecurityState.ActiveFirewallNames
SecurityState.AntispywareOverallStatus
SecurityState.AntivirusOverallStatus
SecurityState.AnyDomainAccountsDirectlyInAdminGroup
SecurityState.AutoupdatesInstalled
SecurityState.AutoupdateStatus
SecurityState.ExtraLocalUserAccountsInAdminGroup
SecurityState.FirewallOverallStatus
SecurityState.IOMMUType
SecurityState.IsBitLockerInUse
SecurityState.IsDefaultEncryptionInUseForSystemDisk
SecurityState.IsDefaultEncryptionSupportedByOs
SecurityState.IsIOMMUAvailable
SecurityState.IsLastLogonUserLocalAdministrator
SecurityState.IsLocalAdministratorEnabled
SecurityState.IsOsUnderCentralManagement
SecurityState.IsPricipalLogonUserLocalAdministrator
SecurityState.IsSecureBootCapable
SecurityState.IsSecureBootEnabled
SecurityState.IsSecureFirmwareTypeInUse
SecurityState.IsTpmChipAvailable
SecurityState.IsTpmChipInUse
SecurityState.MacSecurity.IsSIPAvailable
SecurityState.MacSecurity.IsSIPInUse
SecurityState.OsCentralManagementType
SecurityState.OsCentralManagementTypes.Name
SecurityState.OsCentralManagementTypes.RealmType
SecurityState.OverallDeviceSecurityReadiness
SecurityState.OverallOsSecurityReadiness
SecurityState.OverallUserAccountSecurityReadiness
SecurityState.TpmChipVersion
StartupTime
StartupTimeChangePercentageIn6Months
SystemManagementFirmwareVersion

Software Attributes.Approval
Attributes.BusinessOwner
Attributes.Classification
Attributes.IsLicenseNeeded
Attributes.Lifecycle
Attributes.TechnicalOwner
BackgroundSystemUsageAgents --> see Agent's fields, f.ex BackgroundSystemUsageAgents.Hostname etc.
BackgroundUserUsageAgents --> see Agent's fields, f.ex BackgroundUserUsageAgents.Hostname etc.
DailyUsageAgents --> see Agent's fields, f.ex DailyUsageAgents.Hostname etc.
DeploymentTypes
DeploymentTypesDetected
DevicesDeployed
DevicesMaxConcurrentToday
DevicesMaxToday
DevicesTotalPastMonth
ExtendedAttributesAvailable
ExtendedAttributeTypes
HasNeverBeenUsed
HasUserInstalledInstances
IconId
LastActiveUseDate
LastAnyUseDate
LinkedAgents --> see Agent's fields, f.ex LinkedAgents.Hostname etc.
LinkedLogons.LogonId
LinkedLogons.Name
LinkedLogons.FullName
LinkedLogons.Types
LinkedLogons.LogonName
LinkedProducts.ProductId
LinkedProducts.LinkedApplications
LinkedProducts.Name
LinkedProducts.Version
LinkedProducts.Vendor
LinkedProducts.BackgroundSystemUsageAgents
LinkedProducts.BackgroundUserUsageAgents
LinkedProducts.DailyUsageAgents
LinkedProducts.DeploymentTypes
LinkedProducts.DeploymentTypesDetected
LinkedProducts.DevicesDeployed
LinkedProducts.DevicesMaxConcurrentToday
LinkedProducts.DevicesMaxToday
LinkedProducts.DevicesTotalPastMonth
LinkedProducts.ExtendedAttributesAvailable
LinkedProducts.ExtendedAttributeTypes
LinkedProducts.HasNeverBeenUsed
LinkedProducts.HasUserInstalledInstances
LinkedProducts.IconId
LinkedProducts.LastActiveUseDate
LinkedProducts.LastAnyUseDate
LinkedProducts.LinkedAgents
LinkedProducts.LinkedLogons
LinkedProducts.MonthlyUsageAgents
LinkedProducts.NeverUsageAgents
LinkedProducts.NormalizedVersion
LinkedProducts.OccasionalUsageAgents
LinkedProducts.OldestInstallTime
LinkedProducts.PlatformTypes
LinkedProducts.UsageLevel
LinkedProducts.UsageTimeAverage
LinkedProducts.UserInstalledInstancesAgents
LinkedProducts.UsersMaxConcurrentToday
LinkedProducts.UsersMaxToday
LinkedProducts.UsersTotalPastMonth
LinkedProducts.WeeklyUsageAgents
LinkedTags.EnvironmentId
LinkedTags.TagId
LinkedTags.TagTypeId
LinkedTags.Value
LinkedTags.TagTypeId.Color
LinkedTags.TagTypeId.Contexts
LinkedTags.TagTypeId.EnvironmentId
LinkedTags.TagTypeId.Name
LinkedTags.TagTypeId.Tags
LinkedTags.TagTypeId.TagTypeId
MonthlyUsageAgents --> see Agent's fields, f.ex MonthlyUsageAgents.Hostname etc.
Name
NeverUsageAgents --> see Agent's fields, f.ex NeverUsageAgents.Hostname etc.
OccasionalUsageAgents --> see Agent's fields, f.ex OccasionalUsageAgents.Hostname etc.
OldestInstallTime
PlatformTypes
ProductGroupId
SoftwareScore
UsageLevel
UsageTimeAverage
UserInstalledInstancesAgents --> see Agent's fields, f.ex UserInstalledInstancesAgents.Hostname etc.
UsersMaxConcurrentToday
UsersMaxToday
UsersTotalPastMonth
Vendor
WeeklyUsageAgents --> see Agent's fields, f.ex WeeklyUsageAgents.Hostname etc.
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk