<NULL> Values in Global Filters (Date-Range Reports)

Most of the available properties can include null values. There are different reasons why a value would be null. When these are properties that are set by the application, the possible reasons why a value would be null are: cases where the value has not been set by the application (such as prodBuild never being set), and cases where values are set to an empty string (“”) or to a string containing “<NULL>”.

One other reason is that although these values have been set, the SDK has not yet had time to sync with the servers to provide this new information.

In cases where the properties are set automatically such as hardware or OS related information, the values would be null if the SDK failed to retrieve that value from the OS or if the server failed to identify the value retrieved by the SDK.

Other reasons include cases where Java version is requested from an application that does not use the Java SDK, US state is requested for users who are not running within the US, etc.

The following are the properties that support null values:

prodVersion

prodEdition

prodBuild

prodLanguage

machineId

formFactor

vm

cpuType

cpuCores

ram

resolutionWidth

resolutionHeight

javaVersion

javaVmVersion

javaVmName

javaVendor

javaRuntime

javaGraphics

osLanguage

licenseKey

C01 .. C20 (Custom properties)

os

geography

gpu

Null values can be requested either on their own or as part of a filter containing other values.

The following example would return only cases where the prodVersion is null:

{

      "prodVersion":

          {

              "includeNull": true

          }

}

The following example would return cases where the prodVersion is either 1.1, 1.2 or null:

{

      "prodVersion":

          {

              "type": "stringArray",

              "value": ["1.1", "1.2"],

              "includeNull": true

          }

}

By default, when specifying a filter, null values would not be included. Therefore, in the following example, only clients with prodVersion set to 1.1 or 1.2 will be included, while null values are excluded:

{

      "prodVersion":

          {

              "type": "stringArray",

              "value": ["1.1", "1.2"]

          }

}

However, if no filter is specified, then nulls are included by default. Therefore, if you want to include any value of prodVersion as long as it is not null, a prodVersion filter needs to be included as follows:

{

      "prodVersion":

          {

              "type": "regex",

              "value": ".*",

              "includeNull": false

          }

}

In the case of filters that use sub-properties (os, geography, and gpu), the includeNull filter is to be included in the sub-property and applies to that specific sub-property only. In order to be able to include the includeNull property, instead of providing the value as a string or an array of strings, the value of the sub-property must be a JSON object that contains a property named “value”, and another named “includeNull”. Each of these properties is optional, but at least one of them must be present.

In the case of geography, this has a very particular meaning. Requesting for null “country” value does not return all cases where the country could not be retrieved, but only cases where the continent could be retrieved but the country could not. Similarly, requesting null “usState” returns cases where the continent and country could be retrieved but the US state could not. This does not include clients that are not situated in the US. If you are interested in finding clients where we could not detect any geographical data, the includeNull filter needs to be applied in the continent sub-property.

In the following example, we are requesting cases where we know that the client is within the US but the state could not be identified:

{

      "geography":

          {

              "type": "string",

              "country": "US",

              "usState":

                  {

                      "includeNull": true

                  }

          }

}

In the following example, we are requesting cases where the GPU is either “NVIDIA”, “AMD” or null (unidentified):

{

      "gpu":

          {

              "type": "stringArray",

              "vendor":

                  {

                      "value": ["NVIDIA", "AMD"],

                      "includeNull": true

                  }

          }

}