Difference between revisions of "QPR ProcessAnalyzer Expression Analysis"

From QPR ProcessAnalyzer Wiki
Jump to: navigation, search
(Expression Analysis JSON Configuration)
 
(One intermediate revision by the same user not shown)
Line 122: Line 122:
 
||Cases
 
||Cases
 
||Case objects are initialized. If this preprocessing is not done, Case objects cannot be used.
 
||Case objects are initialized. If this preprocessing is not done, Case objects cannot be used.
||Event.Case, Event.IndexInCase, Event.NextInCase, Event.PreviousInCase
+
||Event.Case, Event.IndexInCase
 
|-
 
|-
 
||CaseEvents
 
||CaseEvents
||Linkage from Cases to Events is initialized. When this preprocessing is made, also ''Cases'' preprocessing needs to be defined.
+
||Linkage from Cases to Events is initialized. When this preprocessing is made, ''Cases'' preprocessing is also made automatically.
||Case.Events, Case.FirstEvent and Case.LastEvent
+
||Case.Events, Case.FirstEvent, Case.LastEvent, Event.NextInCase, Event.PreviousInCase
 
|-
 
|-
 
||Variations
 
||Variations
||Variation objects are initialized. If this preprocessing is not done, Variation objects cannot be used.
+
||Variation objects are initialized. If this preprocessing is not done, Variation objects cannot be used. When this preprocessing is made, ''Cases'' preprocessing is also made automatically.
 
||EventLog.Variations, Case.Variation
 
||EventLog.Variations, Case.Variation
 
|-
 
|-
Line 146: Line 146:
 
Example (3 preprocessings):
 
Example (3 preprocessings):
 
<pre>
 
<pre>
"Preprocessings": ["Cases", "Variations", "FlowsAndEventTypes"]
+
"Preprocessings": ["Variations", "FlowsAndEventTypes"]
 
</pre>
 
</pre>
  

Latest revision as of 09:18, 9 September 2019

QPR ProcessAnalyzer datasource can run QPR ProcessAnalyzer Expression Analysis. Expression Analysis allows configurable objects, such as cases, events, event types or flows, to be divided into configurable dimensions and calculable values (KPIs). In a basic form, the result of this analysis is a table with the following columns: (1) One column for each specified dimension, and (2) at least one column for each specified value. The result of this analysis is a table with one row for each unique dimension value combination.

Expression Analysis relies on QPR ProcessAnalyzer Expression Language:

See also the QPR ProcessAnalyzer Expression Analysis examples.

Expression Analysis Query Syntax

Expression Analysis query allows the following parameters:

  • AnalysisType: Analysis type is 33 for the Expression Analysis.
  • Comparison: Comparison definition as JSON format.
  • ContextType: Either eventlog (default) or generic. When eventlog, the root expression is run in an EventLog's context, i.e.g EventLog's functions and properties can be used. When generic, the root expression is run in the generic context. When using EventLog context, the eventlog is defined using the FilterId parameter (below).
  • Filter: Filter definition as JSON format.
  • FilterId: Used filter object. QPR ProcessAnalyzer model is determined by the defined filter object. If both Filter and FilterId are defined, the filter rules from both are combined.
  • Configuration: Expression analysis configuration defined using JSON. Note that it's not allowed to use linebreaks in the JSON, i.e. the JSON definition must be in one line.
  • RuntimeComparison: When set to 1 (or true), the expression analysis works in the comparison mode (i.e. influence analysis mode, or root causes mode), and the ComparisonEventLog property is available in the expressions. You also need to pass the Comparison parameter which the influence analysis comparison between case sets is based on. The default value is 0 (or false).
  • Variable_<name>: Parameters starting with Variable_ define variables that are available as variables in the KPI expressions with name <name>. For example, when adding Variable_Region=Dallas to the query, there is a variable Region containing value Dallas that can be used in the expressions.

Example query:

{
  "AnalysisType": 33,
  "FilterId": 123456,
  "Configuration": {
    "Root": "Cases",
    "Dimensions": [
      { "Name": "Start Month", "Expression": "StartTime.Month" }
    ],
    "Values": [
      { "Name": "Average Case Duration in Days", "Expression": "Round(Average(_.Duration.TotalSeconds) / 86400, 0)" }
    ],
    "Ordering": [
      { "Name": "Start Month", "Direction": "Ascending" }
    ]
  }
}

Expression Analysis JSON Configuration

Expression analyses is defined using a JSON object which has the following properties:

Property Description
Root Root expression which returns objects that are used as rows when going to the next calculation step which is the dimensioning. The root expression is run in the EventLog context (i.e. for the provided filter). After the root expression is evaluated, the dimension and value expression are run in the root objects context.
Dimensions Array of Dimension objects. The rows are sliced into different groups based on how many unique values the dimension expressions produce. There can be zero to many dimensions. The result data contains a column for each dimension.

If dimension array is empty (i.e. Dimensions: []), all root objects are aggregated into a single row. If dimensions array is not defined at all (i.e. Dimensions: null), each object in the root expression will be as a separate row in the result. Then context for the value expression is (instead of array of objects) a single object.

Each dimension may have the following properties:

Property Description
Dimension Name for the dimension. Dimension name works as the column title for the dimension column. In addition, the dimension name is used when refering to this dimension in the ordering.
Expression Expression to calculate the dimension value for each root object.
IsHidden Is the dimension hidden (true or false). Hiding dimensions don't affect the calculation, but there are no columns in the result for the hidden dimensions.
Values Array of Value objects, which are the actual calculated values (KPI's). Value expressions are calculated for each sliced data group, i.e. for each unique dimension value. Each value object may contain properties defined in the table below.
Ordering Array of Ordering objects. Ordering defined how the result table is sorted.
Property Description
Name Dimension or Value name to sort the data.
Direction Sorting direction, either Ascending or Descending.
ColumnOrdering

An array of column names that defines the order in which the columns are returned. If an array contains a name that does not exist in the results, its value will be returned as null values in the returned result. If an array does not contain a name that is in the original result, then that column will not be returned at all. If ColumnOrdering is not defined, all the result rows will be returned in the defined order so that all the dimensions are returned before the values. Example:

"ColumnOrdering": ["Case Count", "Account Manager", "Average Duration"]
AggregateOthers

When true, all rows that are left out due to the MaximumRowCount limit, are aggregated and shown as the last row. Expressions to calculate the aggregations, can be defined for each dimension and measure using the AggregationExpression property. When the AggregationExpression is not defined, the default aggregated value is null. When the AggregateOthers is used, the maximum number of rows is still the MaximumRowCount, so with the aggregation there is one data row less shown. Default for AggregateOthers is false.

MaximumRowCount

Integer value defining a limit how many rows at maximum are returned by the analysis. The default value is null, which means that all the rows will be returned. If sorting is used, the analysis results are first sorted before the limit is applied.

FirstRow

Integer value defining the starting row number from the analysis results to return. The default value is null, which means that the first row will be the first returned row. Row numbers start from 0. If sorting is used, the analysis results are first sorted before this setting is applied.

RowInitExpression Specifies an expression that is evaluated for every generated row before evaluating the value expressions. RowInitExpression is calculated after the dimension expressions have been calculated and dimensions generated. RowInitExpression can be used to make common calculations and define variables that are needed in several value expressions.
Preprocessings

This parameter is used to explicitly define which preprocessings are done for the EventLog used for the expression analysis, to optimize the performance. If preprocessings are not explicitly defined, all preprocessings are done. Note that if preprocessings needed by the defined expressions are not done, an error occurs when running (e.g. when an expression uses variations and variations haven't been preprocessed). Note also that filter EventLogs are always fully preprocessed, so this setting cannot optimized filter calculation.

When the Preprocessings parameter is not defined, all preprocessings are done. When the parameter is an empty array, no preprocessings are done.

There are the following preprocessings available:

Preprocessing Description Preprocessing is required for the following expression language properties and functions
Cases Case objects are initialized. If this preprocessing is not done, Case objects cannot be used. Event.Case, Event.IndexInCase
CaseEvents Linkage from Cases to Events is initialized. When this preprocessing is made, Cases preprocessing is also made automatically. Case.Events, Case.FirstEvent, Case.LastEvent, Event.NextInCase, Event.PreviousInCase
Variations Variation objects are initialized. If this preprocessing is not done, Variation objects cannot be used. When this preprocessing is made, Cases preprocessing is also made automatically. EventLog.Variations, Case.Variation
FlowsAndEventTypes Flow and EventType objects are initialized. If this preprocessing is not done, Flow and EventType objects cannot be used. Case.Flows, EventLog.Flows, FlowOccurrence.Flow, Variation.Flows, Variation.EventTypes, Flow.From, Flow.To, EventLog.EventTypes, Event.Type, Event.TypeName, Case.EventTimeStampsByType, Case.EventsByType
FlowOccurrences FlowOccurrences objects are initialized. When this preprocessing is made, FlowsAndEventTypes preprocessing is also made automatically. If this preprocessing is not done, FlowOccurrence objects cannot be used. Case.FlowOccurrences, Event.IncomingFlowOccurrence, Event.OutgoingFlowOccurrence and Flow.FlowOccurrences, Case.FlowOccurrencesByType

Using Case.IsConformant and Case.AnalyzeConformance functions require Cases, Variations and FlowsAndEventTypes preprocessings. Using Variation.IsConformant and Variation.AnalyzeConformance functions require Variations and FlowsAndEventTypes preprocessings.

Example (3 preprocessings):

"Preprocessings": ["Variations", "FlowsAndEventTypes"]

Example (no preprocessings):

"Preprocessings": []
Name User definable descriptive name for the Expression analysis.

Properties of the Value object:

Property Description
Name Name for the value. Used only when ValueType is Single.
ValueType

Type of the value. Allowed types are:

  • Single: Produces a single column calculated by an expression (Expression property). (default)
  • Dynamic: There is an expression for defining the actual produced columns dynamically (ValueDimensionExpression property) and another expression (Expression property) for specifying the actual values for the columns.
  • Pivot: Produces as many columns as there are unique values in the expression (Expression property). Columns are ordered according to the order defined by DimensionOrderExpression property.
Expression Behavior depends on the ValueType property:
  • Single: Expression for calculating the value for the single column. The expression is calculated for each row (i.e. the unique dimension combinations), and the expression usually contains aggregations from the group of objects into a single value.
  • Dynamic: Expression for calculating the value for each dynamically generated column specified by ValueDimensionExpression property. The result of the ValueDimensionExpression is accessible via ValueDimension -variable.
  • Pivot: Expression to produce an array, where each item represents a dynamically generated column. The result shown by the Expression analysis is number of items belonging to each column.
AggregationExpression Expression to calculate the aggregated value for the rest of the rows for this column when using the AggregateOthers setting. All the aggregated values are provided as the context (_) for the aggregation expression. Example aggregation exprsesions:

Row count:

"AggregationExpression": "Count(_)"

Sum of values (for numerical columns):

"AggregationExpression": "Sum(_)"

Showing count, minimum and maximum values:

"AggregationExpression": "\"(\" + Count(_) + \" others) \" + Min(_) + \" - \" + Max(_)"
ValueDimensionExpression

(ValueType: Dynamic, Pivot)

Expression used to generate columns in Dynamic and Pivot value types. The expression should return an array where each item represents a column. This expression is executed once when calculating the Expression analysis. For Dynamic type value ValueDimensionExpression field is mandatory, and for Pivot type it's not mandatory.

The result of this expression will be given as the value of variable ValueDimension when evaluating the Expression. For Pivot type value, this can be used to override the default set of columns created automatically based on the actual cell evaluation results. An array of all the actual dimension values created by the actual cell evaluation result is given as context object for the evaluation.

NameExpression

(ValueType: Dynamic, Pivot)

Expression used to generate column names in Dynamic and Pivot value types. This expression is run once for each column, and the expression has as a context the column generated in the ValueDimensionExpression, and as a result the expression should give the column name.
DimensionOrderExpression

(ValueType: Pivot)

Expression used to order the dimensions when pivot value type value is used. If not defined, the following default expression will be used: OrderByValue(_).

PivotAggregationExpression

(ValueType: Pivot)

Expression used to aggregate all the values within one cell of pivot type values. If the expression returns an array of arrays, the first item in the inner array is used as the ValueDimension and the second item is used as the root object when evaluating PivotAggregationExpression. By default, if expression returns only an array of atomic objects, the root object of the evaluation of PivotAggregationExpression is the value of the current ValueDimension.

DefaultValueExpression

(ValueType: Pivot)

Expression whose result is used to fill the "gaps" of the matrix created when pivot value type is used.

JSON structure example:

{
  "Root": "Root expression",
  "Dimensions": [
    {
      "Name": "Dimension 1 name",
      "Expression": "Dimension 1 expression"
    },
    {
      "Name": "Dimension 2 name",
      "Expression": "Dimension 2 expression"
    },
    ...
  ],
  "Values": [
    {
      "Name": "KPI 1 name",
      "Expression": "KPI 1 expression"
    },
    {
      "Name": "KPI 2 name",
      "Expression": "KPI 2 expression"
    },
    ...
  ],
  "Ordering": [ 
    {
      "Name": "Ordered column 1 name",
      "Direction": "Ascending/Descending"
    },
    {
      "Name": "Ordered column 2 name",
      "Direction": "Ascending/Descending"
    },
    ...
  ]
}