Report data may be segmented in up to 3 levels. Each level represents a property. Using multi-level segmentation, you can create hierarchical reports that are used to drill down based on the property values. For example:

• You can create a report that splits all the users based on which edition they are using.
• Then, you can split the user counts for each edition based on product version on level 2.
• Finally, the user counts for each product version can be split up by product build on level 3.

Such multi-level reporting is available only when not splitting by date. Splitting by date is meant to be used in timeline reports, and creating such a hierarchy for each date would result in a huge data set which would only have limited use. When date splitting is used, segmentation with 1 level is still allowed, however. This allows creating timeline reports where each line represents a property value, such as comparing usage trend for version 1 vs version 2.

Segmentation is optional. In order not to split data by any property, you may either:

• Not include a levels property in the request object, or else
• Leave the levels object empty.

The following examples show the difference between:

• Not requesting any segmentation
• Requesting a single level, and
• Requesting 2 levels

In the above examples:

• The first example, 0 Levels, is showing a case where no segmentation is being applied.
• The second example, 1 Level, is showing a response where a single level of segmentation has been requested. In this case, segmentation is being done based on product versions. For each product version, one can see the number of new, active, and lost users within the specified date range. Segmenting by 1 level is also possible in reports that use date splitting, so, in a similar example, one would be able to see how many users were using a specific version on each day within the date range.
• The third example, 2 Levels, shows 2 levels of segmentation. In this example, one can see how many new, active, and lost users were using each version, and then, that data is further split by product edition. A further level is also allowed, so, for example one may choose to segment each product edition by product language.

The properties that are available for segmentation are the same ones that are used for Global Filters in API Reporting. There are 4 properties that require special formatting. These are described below.

Segment levels are to be defined in a property inside the main JSON object named “levels”. This property should contain a JSON object which contains the following members:

• property (string)—The name of the property by which to segment. Note that in case of os, geography, licenseStatus and gpu, a special format is used.
• segments (array)—An array containing a number of JSON objects. The format of these object is described in the Level Segments Format section below.
• sort (string)—Optional property to specify how the segments in this level are to be sorted. Possible values are alpha, new, active, and lost. alpha refers to alphabetical sorting which is based on the segment label. The other 3 are based on the client statuses. Note that if sorting by new, active, or lost users, that particular client status must be included in the clientStatus array. If this property is not included, the data is sorted alphabetically by default.
• sortDirection (string)—Optional property to specify whether to sort in ascending or descending order. Possible values are asc and desc. If not specified, data is sorted in ascending order by default.

Level Segments Format

Segments are defined as JSON objects. A single JSON object may create a single item on a table (or a single series on a timeline chart), or it may create a number of items/series if splitting is enabled. Each object should contain the following:

• type (string)—The data type of the value. Can be string, stringArray, regex, number or numberRange based on whether the property is string-based or numeric. For more information, see Global Filters in API Reporting.
• value (string/array/number)—An exact string, an array of strings, a regular expression or a numeric value. This property should not be used if type is numberRange. Format is based on whether the property is string-based or numeric. For more information, see Global Filters in API Reporting. 
• min (number)—Used only if the type is numberRange. Contains the minimum numeric value to include in this segment. May be combined with max.
• max (number)—Used only if the type is numberRange. Contains the maximum numeric value to include in this segment. May be combined with min.
• split (boolean)—Used only if the type is stringArray or regex. This specifies whether to split the returned data based on each different value matched by the regular expression or array (true), or to join all the clients that match the value as 1 table value or series (false).
• segmentLabel (string)—Used only if split is false or if type is numberRange. This is required to give a name to a series when not splitting by value. It is important that the name given is unique.
• limit (integer)—Optional property to set the limit on the maximum number of table values or series that should be produced by this set of values. To be used only if split is true.

String-Based Segmentation Properties

The following properties are stored as strings:

machineId
clientId
prodVersion
prodEdition
prodBuild
prodLanguage
licenseType
formFactor *
osLanguage
osWordLength *
cpuType *
javaVersion *
javaVendor *
javaRuntime *
javaGraphics *
javaVmVersion *
javaVmName *
vm *
C01 .. C20 (Custom properties)
licenseKey *

NOTE: licenseKey requires a special user permission to be used for segmentation.

NOTE: Properties marked with an asterisk (*) are based on the current (latest known) values.

The type field when using one of the above properties needs to be string, stringArray or regex. A value field is always required. The contents of this field should be according to the specified type.

• If string is specified, then the value field must contain a single string that needs to be matched precisely with the stored data.
• If stringArray is specified, then the value field must contain an array of strings where one of which needs to match precisely with the stored data.
• If specifying a regex, the value field should contain a string which is treated as a regular expression and the stored data will be matched against it using regular expression rules.

Example Using 1-Level Segmentation by string, stringArray, and regex Values

{
    "level1": {
        "property": "prodVersion",
        "segments": [
            {
                "type": "string",
                "value": "1.0"
            },
            {
                "type": "stringArray",
                "value": ["2.0", "2.1", "3.1"],
                "split": false,
                "segmentLabel": "Versions 2 and 3"
            },
            {
                "type": "regex",
                "value": "^4\..*",
                "split": false,
                "segmentLabel": "All version 4"
            },
            {
                "type": "regex",
                "value": "^5\..*",
                "split": true
            }
        ]
    }
}

In the above example, we are requesting a report with multiple segments.

• The first segment contains installations running version 1.0. Notice how this does not require a “split” property since there is only 1 value and therefore no further splitting is possible.
• The second segment contains versions 2.0, 2.1 and 3.1. In this case, the “split” property is required, and since we are requesting the API to combine these 3 versions, we must provide a “segmentLabel” value so that the returned data can be identified.
• The third segment is similar, although in this case the request is built using a regular expression. In this case, all versions starting with “4.” are to be included into one combined segment.

The last segment is different from the rest because we are requesting the API to split the data (split is set to true). Therefore, this can produce much more than 1 segment. In this case, we could see segments such as “5.1”, “5.2”, etc. Notice how since we are splitting, we should not provide a segmentLabel value since the labels are built using the different values that are found in the data.

Numeric Segmentation Properties

The following properties are stored as numeric values:

cpuCores *
displayCount *
ram *
resolutionWidth *
resolutionHeight *
lifetimeRuntimeMinutes *
lifetimeSessionCount *
screenPpi *
javaVmRam *

NOTE: Properties marked with an asterisk (*) are based on the current (latest known) values.

The type field in the above properties needs to be number or numberRange.

• If number is specified, then a value field must also be present. The value field should contain a number, which may contain a decimal point if required.
• If numberRange is specified, then the value field should NOT be used. Instead, the properties min and max are to be used. These refer to the minimum and maximum number to be included in the report. If only one limit needs to be set, the other property is to be left out. Therefore, if you want to include installations with up to 2 display devices, you would not specify a min value, but instead specify only a max and set it as 2.

Example Using 1-Level Segmentation by number, and numberRange Values

{
    "level1": {
        "property": "cpuCores",
        "segments": [
            {
                "type": "number",
                "value": 1,
            },
            {
                "type": "numberRange",
                "min": 2,
                "max": 4,
                "segmentLabel": "2 - 4"
            },
            {
                "type": "numberRange",
                "min": 5,
                "segmentLabel": "5 +"
            }
        ]
    }
}

In the above example, we are requesting a report with 3 segments.

• The first segment contains only installations running on 1 CPU core.
• The second segments contains installations running on 2, 3, or 4 cores (range 2 - 4).
• The last segment contains all installations which are running on a machine with 5 or more CPU cores.

Note how when the type was numberRange, we had do specify a segmentLabel which is a free string that will be used by the user to identify what is being included in that specific segment.

Boolean Segmentation Properties

The following properties are stored ad boolean values:

touchScreen

The type field needs to be boolean, and the value must be true or false. A segmentLabel field is also required

Example Using 1-Level Segmentation by Boolean Value

{
    "level1": {
        "property": "touchScreen",
        "segments": [
            {
                "type": "boolean",
                "value": true,
                "segmentLabel": "Yes"
            },
            {
                "type": "boolean",
                "value": false,
                "segmentLabel": "No"
            },
            {
                "includeNull": true,
                "segmentLabel": "Unknown"
            }
        ]
    }
}

[
    {
        "segmentLabel": "BL and not EXP",
        "blocked": true,
        "expired": false
    },
    {
        "segmentLabel": "WL and ACT",
        "allowed": true,
        "expired": true
    }
]

{
    "level1": {
        "property": "os.platform",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level2": {
        "property": "os.version",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level3": {
        "property": "os.edition",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    }
}

{
    "level1": {
        "property": "geography.continent",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level2": {
        "property": "geography.country",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level3": {
        "property": "geography.usState",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    }
}

{
    "level1": {
        "property": "gpu.vendor",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    },
    "level2": {
        "property": "gpu.model",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "split": true
            }
        ]
    }
}

[
    {
         "segmentLabel": "HISTORICAL and not CURRENT",
         "historical": true,
         "current": false
    },
    {
        "segmentLabel": "Never opted-out",
        "historical": false
    }
]

{
    "level1": {
        "property": "prodBuild",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "includeNull": true
            }
        ]
    }
}

{
    "level1": {
        "property": "geography",
        "segments": [
            {
                "type": "regex",
                "continent": {
                                  "value": ".*",
                                  "includeNull": true
                             }
            }
        ]
    }
}