# statistics.report_fields.{name}
---

node:       profiles.$profile_node_name.statistics.report_fields.$name
infos_node: profile.statistics.report_fields

structure:

  report_fields:
    _:                                            node-list # foreach field
    label:                                        string
    column_label:                                 string
    column_info:                                  string
    database_field:                               string
    average_denominator_field:                    string
    expression:                                   string
    type:                                         string
    sort_type:                                    string
    category:                                     string
    display_format_type:                          string
    custom_display_format_type:                   string
    column_alignment:                             string
    subitems_level:                               int
    show_remainder_value:                         bool
    show_average_value:                           bool
    show_min_value:                               bool
    show_max_value:                               bool
    show_total_value:                             bool
    percent_calculation:                          bool
    sort_by_before_expression_evaluation:         string
    sort_direction_before_expression_evaluation:  string

infos:

  - node:               label
    comment:            Unique report field label.

  - node:               column_label
    comment:            >
                        This overrides the label in report elements. The
                        column_label is used if the table column should have a
                        different label than the report_field label.
                        I.e. the report field "Session pages" should be "Pages"
                        in the table column_header, so we define:
                        label = "Session  Pages"
                        column_label = "Pages"

  - node:               column_info
    comment:            This contains the text which is shown when the user
                        clicks on the table column info icon.

  - node:               database_field
    value:              Node name of an existing database field.
    required_if:        If report field is based on database field.

  - node:               average_denominator_field
    value:              Empty or the node name of another aggregating
                        report field.
    required_if:        If report field is based on database field.
    comment:            A report field which has an average_denominator_field
                        defined becomes automatically a report field upon query
                        fields creation.

  - node:               expression
    required_if:        report field is based on expression and not on database
                        field.
    comment:            The expression can only contain report fields which are
                        based on a database field.

  - node:               type
    values:             [string, int, float]
    default_value:      int
    required_if:        If report field is based on expression.
    comment:            This defines the type in the ssql table for report
                        fields based on expressions.

  - node:               sort_type
    values:             ["", alphabetical, numerical, chronological]
    default_value:      ""
    comment:            This allows to overrirde the default sorting of a ssql
                        table report_field. The default sort type is evaluated
                        automatically by the C++ depending on other report
                        field paramters. If sort_type is not empty then the C++
                        will sort according the specified value.

  - node:               category
    values:
                        - ""
                        - date_time
                        - day_of_week
                        - hour_of_day
                        - day_of_year
                        - week_of_year

    default_value:      ""

    required_if:        >
                        If the report field is based on an expression or if it
                        overrides the database field category. If a report
                        field is based on a database field and the category
                        node exists then it overrides the database field
                        category, also in case that the value is empty.
                        I.e., category="" will set the category to "",
                        regardless of which category is defined in the source
                        database field.

    comment:            >
                        Categories are defined in
                        LogAnalysisInfo/field_categories.cfg
                        The report field category overrides any database field
                        category. A category is usually given in the database
                        field, though a report field with an expression is not
                        based on a database field, hence we allow the
                        definition of a category in report fields as well.

  - node:               display_format_type

    values:

      - value:          string
      - value:          bandwidth
      - value:          date_time
      - value:          day_of_week
      - value:          hour_of_day
      - value:          page
      - value:          hostname
      - value:          integer

      - value:          duration
        comment:        Show in list as "duration (fully written out)"

      - value:          duration_compact
        comment:        'duration as seconds, e.g.: 1y23d 12:34:56'

      - value:          duration_milliseconds
        comment:        'duration as milliseconds, e.g.: 1y23d 12:34:56.789'

      - value:          duration_microseconds
        comment:        'duration as microseconds, e.g.: 1y23d 12:34:56.789012'

      - value:          custom
        comment:        Defines that we use the value of
                        custom_display_format_type for formatting.

    default_value:      "string"

    comment:            >
                        If custom is defined we show a separate
                        custom_display_format_type input field. The string
                        "custom" itself is never used in format(), it is only
                        used to determine from where we get the final display
                        format type which is then set in query_fields. We do
                        not constraint the user on selecting the
                        display_format_type depending on type or any other
                        property. Any display format type is allowed,
                        regardless of the selected report field type.

  - node:               custom_display_format_type
    required_if:        If display_format_type is equal custom
    comment:            >
                        Custom display format types are useful to format i.e. a
                        numerical value as string with a currency symbol like
                        "$ 30.22". format() supports printf-style formatting,
                        so a custom_display_format_type must be in printf-style
                        format, i.e.:

                        custom_display_format_type =
                            "$ %0.4f" (Formats '2.345678' as '$ 2.3456')

                        custom_display_format_type =
                            "%0.2f" (Formats '2.345678' as '2.34')

                        Formatting a value so that it displays a dash which we
                        require in RBAC (we simply use the display format type
                        for hidden fields, value is only set in the query
                        fields display format type!)
                        display_format_type = "%" (Formats 'abc' as '-')

                        Excert from Greg to format values as dash: That takes
                        advantage of the fact that Sawmill uses printf
                        formatting when there is a % in the string. But %- is
                        an invalid printf format string, so it renders as "";
                        that makes the whole thing "-".

  - node:               column_alignment
    values:             ["", left, right]
    default_value:      ""
    comment:            column_alignment defines the alignment in html table
                        columns. If column_alignment is empty (auto) we align
                        non-aggregating fields left and aggregating fields
                        right. If left or right is specified then we align
                        accordingly, regardless if aggregating or
                        non-aggregating field.

  - node:               subitems_level
    value:              '>= -2'

    values:

      - value:          '-2'
        comment:        source item field (date_time timestamp in case for
                        date_time database field in log_detail report)

      - value:          '-1'
        comment:        bottom_level field

      - value:          '0'
        comment:        hierarchical field

      - value:          '>= 1'
        comment:        The integer number specifies the subitems level.

    default_value:      '-1'

    required_if:        If report field is based on a database field and where
                        the log field on which the database field is based on
                        is not of type "flat" and not of type "agent".

  - node:               show_remainder_value
    default_value:      true
    required_if:        if aggregating database field
    comment:            If set to true it will show the calculated remainder
                        value in the remainder row cell. If set to false it
                        will show a "-" dash in the remainder row cell.

  - node:               show_average_value
    default_value:      true
    required_if:        if aggregating database field
    comment:            If set to true it will show the calculated average
                        value in the average row cell. If set to false it will
                        show a "-" dash in the average row cell.

  - node:               show_min_value
    default_value:      true
    required_if:        if aggregating database field
    comment:            If set to true it will show the calculated min value in
                        the min row cell. If set to false it will show a "-"
                        dash in the min row cell.

  - node:               show_max_value
    default_value:      true
    required_if:        if aggregating database field
    comment:            If set to true it will show the calculated max value in
                        the max row cell. If set to false it will show a "-"
                        dash in the max row cell.

  - node:               show_total_value
    default_value:      true
    required_if:        if aggregating database field
    comment:            If set to true it will show the calculated total value
                        in the totals row cell. If set to false it will show a
                        "-" dash  in the totals row cell.

  - node:               percent_calculation

    values:
      - value:          sum
      - value:          sum_or_subsum

      - value:          none
        comment:        (column value is already a percent value) - Not
                        implemented, planned for later.

      - value:          column_value
        comment:        (Get base value from another aggregating report field)
                        Not implemented, planned for later.

    default_value:      sum
    required_if:        if aggregating database field

    comment:            >
                        sum and subsum basically defines the base value for
                        percentage calculation for the inner rows (sub-table)
                        of a pivot table.

                        If sum we calculate all percentages from the sum of the
                        outer rows (main-table).

                        If sum_or_subsum then the sub-sum of the inner rows is
                        equal 100%, so the base value for the inner rows
                        percentage calculation is the sub-sum value and not the
                        sum value.

  - node:               sort_by_before_expression_evaluation
    value:              Empty or node name of an existing report field.
    required_if:        Optionally if report field is based on expression.
    comment:            If a report field is specified then the ssql table
                        becomes sorted by this report field before expressions
                        are evaluated.

  - node:               sort_direction_before_expression_evaluation
    values:             [ascending, descending]
    default_value:      descending
    required_if:        If sort_by_before_expression_evaluation is defined.
    comment:            This defines the sort direction for
                        sort_by_before_expression_evaluation.

...











