Reporting Widget

reportingId

String

YES

The id of a Reporting Object Configuration which this widget will target. The request will be executed by using the information of this configuration, such as the collection name.

-

bordered

Boolean

NO

Apply a border around the chart

true, false

title

Boolean

NO

If true, an internationalized title and subtitle will be displayed above the chart

true, false

contract

ReportingWidgetContractConfiguration

YES

A ReportingWidgetContractConfiguration specifying the different criteria used by the widget for displaying the filter elements. It is also used for validating the submitted criteria.

-

display

ReportingDisplayConfiguration

YES

Describes how data should be represented.

-

associations

List<ReportingWidgetAssociationConfiguration>

NO

A list of "associations" between widget. When a target widget is associated, it will use the criteria of the source widget query to execute its own query. For instance a reporting widget can be associated with a list widget to display details.

-

criteria

List<CriteriaDefinition>

YES

A list of criteria configurations. Note that they must be equal to the set (or a subset) of the allowed criteria of the Reporting Object Configuration referenced in reportingId. 

-

criterion

Criterion

YES

Configuration of one criterion.

-

name

String

YES

The name of the criterion. Must match the one in the target Collection.

-

controlType

ReportingCriteriaControlType

NO

Configuration for the type of control in the UI. This will also be used to infer the criteria value type.

-

mandatory

Boolean

NO

Indicates if a non null value must be provided at request time. If a fixed value (see below) is also provided it will fulfill the mandatory constraint.

In the UI, mandatory criteria will be displayed in the order of declaration. They cannot be removed from the criteria selector.

true,false

allowFixedValueOverride

Boolean

NO

If true, the fixed value will only apply if the user's request does not contain the criteria. This effectively transforms the fixed value configuration into a default value configuration.

true,false

dynamicFixedValue

ComputeRule<?>

NO

A Compute Rule specifying a fixed value for this criteria. If it is configured, the criteria will always have this value and it will not be available in the UI (unless allowFixedValueOverride is true). This is a good way to force some criteria values for a particular chart (for instance to only target authentications for a specific country)

-

staticFixedValue

String

NO

Alternative to dynamicFixedValue as a single static value (String only).

-

displayFixedValue

Boolean

NO

Only useful when a fixed value is provided. If true, the fixed value will be displayed in read-only instead of being hidden

true,false

fixedMatchOperator

Operator (enum)

NO

EQUALS,NOT_EQUALS, LIKE (regex matching), NOT_LIKE (regex matching), STARTS_WITH (regex matching), ENDS_WITH (regex matching), GREATER, LESS, GREATER_OR_EQUALS, LESS_OR_EQUALS, BETWEEN, IN, NOT_IN, IS_NULL, IS_NOT_NULL (Meaning that the value is not "NULL" or "" (empty string) and if the value is a list it needs to have at least one element (non empty lists))

values

ReportingCriteriaValues

NO

Holds information for the initial and available value(s) in the UI criteria forms.

-

valueType

ValueType

NO

Choice types (ending with _CHOICE) will require that the choice values are supplied as well (see "values" property of this object).

Range type values (ending with _RANGE) will use the first and last element of the supplied choice values as lower and upper limit (in this order). 

OBJECT_REFERENCE type will allow to search for an object reference.

Note that the search of OBJECT_REFERENCE is done "live" on the Identity Management Service at the time of search. Reporting data are "archived" data, so it is possible that a reference that is present in the reporting collection representing an object is not synchronised anymore with what this object is currently (modified, deleted, type migration etc.)

Also note that it is possible to change the selected attribute when picking a result of object references using the alternativeSelectionAttribute property (see configuration of the reference widget)

Note that the value type of the control declared here will be used to infer the value type of the criteria to send (Ex: INTEGER_RANGE will map to a INTEGER value type criteria in the request). This value type has precedence over the type declared in the Reporting Object Configuration.

TEXT, TEXT_CHOICE, DATETIME, DATETIME_RANGE, DATE, DATE_RANGE, INTEGER, INTEGER_RANGE, INTEGER_CHOICE, FLOAT, FLOAT_RANGE, FLOAT_CHOICE, BOOLEAN, OBJECT_REFERENCE

multivalued

Boolean

NO

Indicates if the criteria can be multivalued. The UI will allow to input multiple values.

true,false

objectReferenceWidget

AdvancedObjectReferenceEditWidget

NO

Must be configured when the value type is OBJECT_REFERENCE. This widget will be used for searching references. It has the same configuration as any advanced object reference widgets used in search features for instance.

-

reportingReferenceSearch

ReportingReferenceSearch

NO

Sometimes a criteria value is too hard to input for a user, such as a technical code without meaningful naming. An easier way would be to provide an intermediary search for the criteria value itself (this is similar to the concept of nested object reference search used in scope widget. Example: search the technical id of the manager of user john.doe by first searching in a list of managers and selecting john.doe's one).

Say we provide a technicalCriteria as TEXT control. If this reportingReferenceSearch is configured, the control will display as a search input with a reporting list that can be configured independently to search for the desired technicalCriteria value. The configuration must also indicate which path on the result should be used as the value of the criteria when selecting a row.

-

options

ReportingCriteriaControlTypeOptions

NO

Options for the control type

-

reportingListWidget

ReportingListWidget

YES

An independent Reporting List Widget that can target a collection with its own criteria

-

valuePath

String

NO

A path to the wanted value on the list result (the reporting list results are objects, this value indicates the path to the property that should be used as the value when the user select a row)

-

i18n

String

NO

An i18n key that will have in its context the selected row. Will be used to display the selected result.

-

addRangePeriod

String (valid period duration)

NO

If this option is null, a DATETIME criteria will be matched with an EQUAL operator for the single selected value. (If fixedMatchOperator is not used, EQUAL is the default operator).

This may be what we want (for instance matching the date exactly).

However, we might want the single datetime selection to still represent a range.
For instance, selecting a unique date to see all authentications during the day (a 24H  implicit range).

Instead of displaying a range selector (using DATETIME_RANGE or DATE_RANGE) we want to allow the selection of a single date
in the UI while applying a range automatically.

This cannot be accomplished simply by changing the operator, we need to tell the configuration that we want an automatic range.

This option serves to indicate an optional amount of time to add automatically to the selected date as the upper bound of a range.
If configured, the criteria will now be matched BETWEEN the two values: the lower bound selected by the user and
the automatically calculated upper bound.

Example:
We want a single date selection in the UI corresponding to the range of the entire selected day.
Therefore we would configure "P1D" in the option on a DATE/DATETIME criteria.

-

periodSelection

ReportingPeriodSelection

NO

Allows to change the display of the period selection.

Only applied when the valueType is DATETIME_RANGE or DATE_RANGE.

-

mode

ReportingPeriodSelectionMode

NO

Specify the period selection mode.

• IN_LAST : allows selection of a period from “now”(browser time) to the selected value in the past.

• MONTH : allows selection of a period by range of one month.

• DAY : allows selection of a period by range of one day.

IN_LAST, MONTH, DAY

dynamicInitValue

ComputeRule of FEATURE category

NO

The initial value for the filter in the UI. Only for frontend purpose. It can be changed by the end user later. This will only offer a way to prefill a criteria for the user.

-

staticInitValue

String

NO

Alternative to dynamicInitValue with a single string.

-

dynamicChoiceValues

ChoiceRule of FEATURE category

NO

Provide a list of choices when the value type is a _CHOICE. These values must be the one that exists in the Collection for this particular criteria. It is possible to retrieve values from "filters" Collections using an API.

The ".filters" collections are currently not created nor updated automatically.

staticChoiceValues

List<String>

NO

Alternative to dynamicChoiceValues as a list of strings

-

type

Enum

NO

An enum of available charts

NONE (no graph), only usefull for association with other chart

XY_CHART (bar chart)

PIE_CHART (pie chart, the round one with slices)

COUNTER_CHART (for displaying a single value)

TIMELINE_CHART

PLATFORM_AVAILABILITY_CHART

GEO_MAP_CHART

displayOnInit

Boolean

NO

If true, the chart will be displayed initially without requiring to click the "Apply" button of the criteria panel first.

true, false

legend

ReportingWidgetLegendConfiguration

NO

Configuration for the chart legend. May not be applicable to all charts.

-

size

ReportingWidgetSizeConfiguration

NO

Control the sizing of the chart

-

display

Boolean

NO

Should the legend be displayed or not

true,false

cssWidth

String

NO

A CSS value for the chart width

100%

cssHeight

String

NO

A CSS value for the chart height

500px

radiusPercent

Integer

NO

A number between 10 and 100 that represents the radius of the chart.

Only for Pie Chart.

50

xySeries

List <ReportingXYChartSeriesConfiguration>

NO

Describes a list of XY series. This type of series is defined by a unique id and a configuration for the X and Y data.

-

axes

ReportingWidgetAxesConfiguration

NO

Describes the lists of X and Y axis.

-

xySerie

ReportingXYChartSeriesConfiguration

NO

Configuration of one xy serie.

-

id

String

YES

A unique identifier for the serie

-

dataX

ReportingXYChartSeriesDataConfiguration

YES

Describe the property and axis used for the X data (horizontal)

-

dataY

ReportingXYChartSeriesDataConfiguration

YES

Describe the property and axis used for the Y data (vertical)

-

property

String

YES

The name of the property to use for plotting data. This can correspond to a field name in the response or an expression.

Time operators
In order to group elements by date granularity of hour, day, week, month and year, the REP service will add new fields that correspond to the chosen granularity during the aggregation phase. This granularity is specified by using one of "hour(field)", "day(field)", "week(field)", "month(field)" or "year(field)" where "field" is the name of an ISODate field in the Collection.
The field will be projected in the REP response as a camelized string consisting of the property and operator stripped of any dot:
(Example: hour(date) => _dateHour, day(_id.date) => __iddateDay)

hour(date) => _dateHour 
day(date) => _dateDay
week(date) => _dateWeek 
month(date) => _dateMonth 
year(date) => dateYear

Aggregation operators

Values can be aggregated inside a group using an operator. The aggregated value will be returned as a field whose name consists of the camelized concatenation of the field name and operator name.
If the field is a nested path, the dot will be stripped.
(Example: sum(nb) => _nbSum, avg(salary.net) => _salarynetAvg).

sum(nb) for the sum over the field "nb" in the group (property _nbSum) 
avg(nb) for the average over the field "nb" in the group (property _nbAvg) 
count() for the count of elements in the group. Note that this operator does not aggregate over a field but count elements (property _count)
min(nb) for the minimum of the field "nb" in the group (property _nbMin)
max(nb) for the maximum of the field "nb" in the group (property _nbMax)

In all cases the property must be compatible with the operator and/or axis type.

-

axisId

String

YES

Must match to the id of an existing axis declared in the axes configuration. The series will use the axis type as its own data type, so they need to be configured in accordance.

-

axesX

List<ReportingWidgetAxisConfiguration>

NO

A list of axes configuration. These axes can be used for the horizontal part of the graph.

axesY

List<ReportingWidgetAxisConfiguration>

NO

A list of axes configuration. These axes can be used for the vertical part of the graph.

axis

ReportingWidgetAxisConfiguration

NO

Configuration of one axis.

-

id

String

YES

A unique id that can be referenced by a series

-

type

Enum

NO

The type of axis. It will also through reference be used by any series that reference this axis.

CATEGORY: For labels, textual data. Note that it can also be used for date data if the date is to be treated as a single element on chart column click (otherwise the resulting click will provide a range).

DATE: For date and datetime based data.

VALUE :For numeric value

rendering

ReportingWidgetAxisRendering

NO

Options for the rendering of the axis

-

labelRotation

Integer

NO

Integer from 0 to 360 to rotate the axis labels.

This is useful if the labels start overlapping.

Exemple: 45 will rotate the label to be slanted to the bottom right

0

minGridDistance

Integer

NO

Set the minimum distance between grid lines.

Increasing this number will result in sparser grid lines and labels.

Decreasing this number will result in denser grid lines and labels.

120

pieSeries

List<ReportingPieChartSeriesConfiguration>

NO

Describes a list of serial series. This type of series is defined by a unique id and a configuration for the category and value

-

pieSerie

ReportingPieChartSeriesConfiguration

NO

Configuration of pieSerie.

-

id

String

YES

A unique id for the series

-

categoryProperty

String

YES

The name of the property to use for representing a slice of the pie chart. 

This can correspond to a field name in the response or an expression

Example :

In a data thats looks like { "country": "France", "population": 560 }, "country" is a category property.

-

valueProperty

String

YES

The name of the property to use for representing a slice size of the pie chart. Must map to a numeric value.

This can correspond to a field name in the response or an expression

Example :

In a data thats looks like { "country": "France", "population": 560 }, "population" is a value property.

-

aggregationExpression

String

NO

An aggregation expression (sum(nb), avg(salary) etc (See "Field Operators")) that represent the UNIQUE value of this counter. Because this type of chart will not provide any group for the aggregation, it is expected that the result contains a singleton element.

-

icon

String

NO

An icon selector (Font Awesome like "fa fa-user" or Simple line icons like "icon-user")

-

title

String

NO

I18N key for the title of the counter

-

text

String

NO

I18N key for a text inside the counter

-

counterColor

String

NO

A Metronic theme CSS color name for the counter number color

dark

borderColor

String

NO

A Metronic theme CSS color name for the border color of the counter

grey

initialZoom

Float

NO

Configure the initial zoom level of the map chart.

Most tiles providers give tiles in a 256px square image.
When we represent the world at zoom level zero, it’s 256 pixels wide and high.
When we go into zoom level one, it doubles its width and height, and can be represented
by four 256-pixel-by-256-pixel images. At each zoom level, each tile is divided in four, and its size
doubles, quadrupling the area. (in other words, the width and height of the world is 256·2^zoomlevel pixels)
Most tile services offer tiles up to zoom level 18, depending on their coverage.

• 2

padding

String

NO

CSS padding around the map (ex: "0 20%")

-

centerLat

Float

NO

Initial latitude of the map center

0

centerLong

Float

NO

Initial longitude of the map center

0

maxZoom

Float

NO

Maximum zoom level allowed. If not filled, it will default to the maximum allowed by the tile provider

-

minZoom

Float

NO

Minimum zoom level allowed. If not filled, it will default to the minimum allowed by the tile provider

-

propertyLat

String

YES

The property name in the document holding the latitude value

location_data.latitude

propertyLong

String

YES

The property name in the document holding the longitude value

location_data.longitude

propertyCity

String

YES

The property name in the document holding the city value

location_data.city

timeline

ReportingTimelineChartConfiguration

NO

Configuration for a timeline chart. This chart uses data that can be organized serially based on a DATETIME property.

-

dateProperty

String

NO

The name of the DATETIME field in the documents that will be used for plotting the timeline

-

timelineColor

String

NO

The color of the timeline trail as an hexadecimal string (ex: "#67b7dc")

-

levelCount

Number

NO

The number of "turns" in the timeline. Allows to increase the number of items displayed.

It will often require to adjust the height of the chart as well.

-

horizontal

Boolean

NO

Toggle the timeline from vertical to horizontal layout

true,false

bullets

List<ReportingTimelineBulletConfiguration>

NO

A list of bullet configuration.

-

initialRange

ReportingTimelineRangeConfiguration

NO

Allow to customize the initial display range of the timeline (using the range window. The range window is displayed at the top of the timeline and allows zooming on a part of the timeline).

-

tooltipConfiguration

ReportingTimelineTooltipConfiguration

NO

Global configuration for all tooltips

-

bullet

ReportingTimelineBulletConfiguration

NO

Configuration of one bullet.

-

matchProperty

String

NO

The name of the property on the documents on which the value should be checked for comparison to determine if this bullet should be used for displaying this document (if matchValue corresponds).

The pair of matchProperty / matchValue should be unique in order to always use the same bullet for a specific type of event.

-

matchValue

String

NO

The value to match in order for this bullet to be used.

-

color

String

NO

Color of the bullet (as hex value)

#a367dc

icon

String

NO

Font awesome CSS class for the bullet icon (ex: "fa fa-bullseye")

fa fa-bullseye

iconColor

String

NO

Color of the icon (as hex value)

#000000

tooltipContent

ReportingTimelineBulletTooltipContent

NO

Configuration for the tooltip of this bullet

-

title

String

NO

The title of the tooltip. Can be an i18n key.

-

subtitle

String

NO

The subtitle of the tooltip. Can be an i18n key.

-

contextSection

ReportingTimelineBulletTooltipContextSection

NO

A section for configuring specific content that should not go in the main table.

-

description

String

NO

Can be i18n key.

If not empty, the description will be displayed above the table

-

textColor

String

NO

A color for the text of the tooltip (the tooltip color is inherited from the bullet "color" property).

-

link

ReportingTimelineBulletTooltipLink

NO

If configured allows to display a button link in the tooltip.

-

table

ReportingTimelineBulletTooltipTable

NO

Configuration of a two columns table to display 

-

description

String

NO

An optional description to display in this section. Can be an i18n key.

-

table

ReportingTimelineBulletTooltipTable

NO

Configuration of a two columns table. Same configuration as "tooltipContent.table"

-

url

String

NO

URL to redirect. Can contain template variable. 

Ex: "features/myDIsplayFeature/{object.id}"

-

linkTarget

Enum

NO

How to open the link (in same window or new tab)

SELF, NEW_TAB

label

String

NO

Label of the button. Can be i18n key.

-

rows

List<ReportingTimelineBulletTooltipTableRow>

NO

A list of rows configuration (in xml each are under a <row> wrapper).

-

row

ReportingTimelineBulletTooltipTableRow

NO

Configuration of one row of bullet tooltip table.

-

title

String

NO

The key name/title. For instance "Browser". Can be i18n key.

-

dataKey

String

NO

The path on the document containing the value to display in the second cell. For instance "user-agent.browser".

-

type

Enum

NO

The type of data to display

TEXT, DATE_TIME

dateFormat

String

NO

A recognized date format or a moment format (ex: DAY_MONTH_YEAR_LONG, L HH:mm:ss, etc.)

DAY_MONTH_YEAR_LONG

startRange

Float (between 0 and 1)

NO

The position of the initial left handle of the range window

0

endRange

Float (between 0 and 1)

NO

The position of the initial right handle of the range window

1

maxWidth

Number

NO

Maximum width of a bullet tooltip (in pixel)

500

maxHeight

Number

NO

Maximum height of a bullet tooltip (in pixel)

500

orientation

Enum

NO

VERTICAL: The tooltip is displayed above the bullet (can go out of screen)

HORIZONTAL: The tooltip will try to place itself horizontally, taking the viewport space into account

VERTICAL, HORIZONTAL

widgetId

String

YES

The target widget id. Must match one that is configured in the same feature

-

allowEditCriteria

Boolean

NO

Indicates if the target widget (referenced by widgetId) is allowed to propose an "Edit filters" button to edit the criteria provided by the association and/or to add new criteria.

true, false

propagation

ReportingWidgetPropagationOptions

NO

Options for the association propagation

-

criteriaMapping

List<ReportingWidgetAssociationCriteriaMapping>

NO

Criteria used by different collections will mostly have a different name/path.
This allows to remap the criteria between the source and target widget.

"associations": [
   {
     "widgetId": "list-widget",
     "allowEditCriteria": true,
     "criteriaMapping": [
      	{
       		"source": "ua",
       		"target": "user-agent.browser.family"
        }
	  ]
	}
]

If the forwarded value should be replaced, the "conversion" property allows to do that.

"associations": [
   {
     "widgetId": "list-widget",
     "allowEditCriteria": true,
     "criteriaMapping": [
      	{
       		"source": "ua",
       		"target": "user-agent.browser.family",
            "conversion": {
               "staticValue": "CHROME"
            }
        }
	  ]
	}
]

In this case, the association will forward a criteria "user-agent.browser.family" with the static value "CHROME" instead of the value of the original criteria.

-

strategy

Enum

NO

• ALWAYS:  Always propagate the association when new data is received in the source widget. This means that associated widgets will be displayed on any events (clicking the apply button
  of the source widget or selecting an element in the chart for instance).

• SELECTION: Only propagate the association when an element is selected in the source widget. The "selection" action depends on the widget type (column click on a XY chart, slice clickon Pie Chart, etc.).

Some widgets can ignore the strategy if their behavior cannot be different (counter chart for instance).

ALWAYS, SELECTION

mapping

ReportingWidgetAssociationCriteriaMapping

NO

Configuration of one criteria mapping.

-

source

String

YES

The name of the criteria in the source widget.

It is possible to declare a source criteria that does not exists on the source widget filter contract.

This case happens when the criteria is received from data and needs to be passed.
For instance an XY chart may declare only one criteria "status" in its contract for filtering the result but it can declare an association of criteria "date" because the data result contains a field "date". This "date" value will be passed as criteria to the target widget, but the source widget itself does not necessarilly have to allow a filter for the criteria "date".

This can also be used when clicking a reporting list row to transfer data results as criteria, even though the list does not allow to filter on those criteria itself.

-

target

String

YES

The name of the criteria in the listener widget.

Unlike the source criteria, the target criteria name must be part of the filter contract of the target widget. This is because the target widget will use the received value for filtering.

conversion

ReportingWidgetAssociationCriteriaMappingConversion

NO

Allow to convert the value forwarded by the association.

staticValue

String

NO

If not null, the association will replace and forward this value instead of the original value of the source criteria.

-