System Library

From QPR ProcessAnalyzer Wiki
Revision as of 12:27, 19 November 2024 by MarHink (talk | contribs) (→‎Parameters)
Jump to navigation Jump to search

System library is a collection of Expression Language functions and properties that provide additional tools for scripting Process Analyzer functionalities. System library is referenced in scripts via _system-property, which provides additional properties dedicated for different areas of interests for scripting.

The following hierarchy shows the properties and functions available in System Library:

Parallel.Run

Runs given functions in parallel.

Parameters

  • functions:
    • An array of functions to run in parallel.

Return value

An array of results returned by the called functions, in the same order as the function generating them in the functions-parameter.

Example

The following script uses _system.Parallel.Run to run three functions:

  • SAP-extraction from VBAK-table in SAP (connection parameters defined in connectionParametersDict-dictionary).
  • Transform the extracted data by adding a new column.
  • Load the data into data table identified by dataTableId.
function ExtractTransformAndLoad(extractFunc, transformFunc, loadFunc)
{
  let rawDataFlow = extractFunc();
  let transformedDataFlow = ToDataFlow();

  _system.Parallel.Run([
    () => Catch({
      let df;
      while (!IsNullTop(df = rawDataFlow.Collect(#{"CollectChunk": true}))) {
        transformedDataFlow.Append(transformFunc(df));
        WriteLog(`A chunk having ${df.NRows} rows has been transformed.`);
      }
      if (rawDataFlow.HasError) {
        transformedDataFlow.Fail("Error occurred during data extraction.");
      }
      else {
        transformedDataFlow.Complete();
      }
    }, {
      transformedDataFlow.Fail("Error occurred during transformation calculation.");
    }),
    () => {
      loadFunc(transformedDataFlow);
    }
  ]);
}

ExtractTransformAndLoad(
  () => ExtractSap(connectionParametersDict.Extend(
    [
    "FieldNames": "VBELN,ERDAT,ERZET,ERNAM,NETWR,WAERK", 
    "QueryTable": "VBAK",
	"Options": ["VBELN BETWEEN '0000017448'" ,"AND '0060000042'"],
    "UseGateway": true
    ])
  ),
  df => df.SetColumns(["Test": () => `${Column("NETWR")} ${Column("WAERK")}`]),
  dataFlow => {
    DataTableById(dataTableId).Import(dataFlow, ["Append": 0]);
  }
);

DataTableById(dataTableId).SqlDataFrame.OrderByColumns(["VBELN"], [true]).Collect()

RootCauses.FindRootCausesDataFrame

Finds root causes for a particular process phenomenon by comparing properties of selected cases against those of all cases in given model (#27619#).

Based on the similar in-memory function: EventLog.FindRootCauses.

Parameters

  • model:
    • Model object of a model whose data tables are used to calculate the root causes.
  • parameters:
    • A parameter convertible to a StringDictionary object with the following supported key-values:
      • Filter:
        • Filter json (#30921#) that is applied to the event log before calculating root causes.
      • Selection:
        • Selection json (#30927#) that defines selected cases to find root causes for. Is applied on top of the filtered event log (specified by Filter parameter).
        • If nothing is selected, 100% of cases are counted as selected.
      • CaseAttributeTypes:
        • An array of strings with the names of case attributes included into the root causes.
        • Only case attributes of type string, integer or boolean are included.
        • If CaseAttributeTypes is null or empty string or not specified, all case attributes having type "String" are included into the root causes.
        • If the model doesn't have a case attribute with the specified name, an error message is shown.
      • EventAttributeTypes:
        • An array of strings with the names of event attributes included into the root causes.
        • Only event attributes of type string are included.
        • If EventAttributeTypes is null, all event attributes having type "String" are included into the root causes.
        • If EventAttributeTypes is empty array or not specified, event attributes not applied to the root causes.
        • If the model doesn't have an event attribute with the specified name, an error message is shown.
        • Analysis column Name should contain Event Attribute Name.
        • Analysis column Value should contain Event Attribute Value and number of occurrences in case: <value> (count).
        • Analysis column Type should have "EventAttributeValue" as its value.
      • WeightingExpression:
        • Expression providing weights for each case.
        • Expression, if defined, must be any of the following types:
        • A row is filtered out of result if expression result is null.
      • MaximumRowCount:
        • The maximum number of the most and least contributing root causes to return. Thus, the actual number of returned rows can be at most two times this value (if specified).
        • If undefined, 200 is used.
        • If set to 0, all rows are returned.
      • MinValueUsage:
        • The minimum total usage of a value included into the comparison. The number of cases having every returned value should be at least given percentage (a float value between 0.0 and 1.0) of all the compared cases.
          • If not defined or null, all values are included (=default).
      • MaxNumUniqueValues:
        • Maximum number of unique values to include into the comparison for each attribute column. If the amount of unique values for any attribute exceeds this value, only given number of attributes are included that have the highest usage.
        • If not defined or null, all values are included (=default).
      • IncludeOthers:
        • Should the rest of the attribute values not included due to MinValueUsage or MaxNumUniqueValues filtering be included as an aggregated "Others" value?
        • If given any string value, that value is used as the value for all the aggregated values.
        • Default = undefined => others values will not be included into the results.
      • ValueIfNull: Value used to indicate null-values.
        • Default = "(blank)".
        • Must be not null.

3 Returns a SqlDataFrame object (#70611#) with the following columns:

3.1 Common columns

3.1.1 Type: type of the root cause

3.1.1.1 "CaseAttributeValue" for case attributes

3.1.1.2 "EventAttributeValue" for event attributes

3.1.2 Name:

3.1.2.1 When type is CaseAttributeValue, case attribute name

3.1.2.2 When type is EventAttributeValue, event attribute name

3.1.3 Value:

3.1.3.1 When type is CaseAttributeValue, case attribute value

3.1.3.2 When type is EventAttributeValue, event attribute value and number of occurrences in case

3.1.4 Total: total number of cases having the found root cause

3.1.5 Selected: Number of cases that have the found root cause and belong to the selected cases

3.1.6 Compared: number of cases that have the found root cause and don't belong to the selected cases

3.2 Columns when WeightingExpression not have value

3.2.1 Contribution: the number of cases which contribute to the deviation from the average percentage of selected cases among all analyzed cases

3.2.2 ContributionPercentage: the percent of cases which contribute to the deviation from the average percentage

3.2.3 DifferencePercentage: deviation in percentage between selected cases with the found root cause and the average percentage of selected cases among all analyzed cases

3.1.4 SelectedPercentage: percent of selected cases that have the found root cause out of all cases with that root cause

3.3 Columns when WeightingExpression have value

3.3.1 Contribution: Sum of case weights which contribute to the deviation from the average percentage of selected case weights among all analyzed cases

3.3.2 ContributionPercentage: the percent of case weights which contribute to the deviation from the average percentage

3.3.3 DifferencePercentage: deviation in percentage between selected case weights with the found root cause and the average percentage of selected case weights among all analyzed cases

3.3.4 SelectedPercentage: percent of selected case weights that have the found root cause out of all case weights with that root cause

3.3.5 SelectedWeight: Sum of weights that have the found root cause and belong to the selected cases

3.3.6 ComparedWeight: Sum of weights that have the found root cause and don't belong to the selected cases

3.3.7 TotalWeight: Sum of weights of all cases with that root cause

4. Notable differences between this function and FindRootCauses (#71058#) used for in-memory event logs:

4.1. In FindRootCauses, Zero-weighted contibution rows are removed from the results.

4.2. Non-numeric case cost in FindForDataFrame causes and exception to be thrown. Not in FindRootCauses, where is behaves as if null was used.

4.3. All the case-data table columns can be used as CaseAttributeTypes in FindForDataFrame, even the case id column, which can't be used in FindRootCauses.

4.4. WeightingExpression is given as SqlExpression, not expression language expression as in FindRootCauses.

4.5. FindForDataFrame only supports querying one type of columns at a time. Querying, e.g., columns having both string and integer values will throw an exception.

4.6. If an empty array is given for CaseAttributeTypes-parameter, FindForDataFrame throws an exception, whereas FindRootCauses returns a result without any rows.

4.7. FindForDataFrame converts attribute values to string, because internally it uses UNPIVOT instruction for calculating Value column (requires same data type for unpivoted columns). So even if numeric case attribute is used, Value column will contain strings and sorting by Value will use string comparison.

Examples:

{

  "ProcessingMethod": "DataFrame",

  "Root":"let m = _; _system.RootCauses.FindForDataFrame(m, _query.Configuration.Parameters.FindRootCausesParameters.Clone().Extend(#{\"Filter\": _query.Configuration.Filter}))",

  "Parameters": {

   "FindRootCausesParameters": {

     "CaseAttributeTypes": ["Account Manager","Customer Group","Product Group","Region"],

    "Selection": {"Items":[{"Type":"IncludeCases","Items":[{"Type":"CaseAttributeValue","Attribute":"Product Group","StringifiedValues":["0Hats"]}]}]},

     "MaxNumUniqueValues": 2,

     "MaximumRowCount": 1000,

     "MinValueUsage": 0.20,

     "WeightingExpression": "Column(\"Cost\")"

   }

  },

  "Ordering": [

   {"Name": "Contribution", "Direction": "Descending"}

  ]

}

Calculates root cause analysis for given model using parameters read from the query configuration.

Utils.GetSampledEvents

foo

Utils.RunFunctionWithParallelLogging

foo

Retrieved from "https://wiki.onqpr.com/pa/index.php?title=System_Library&oldid=25459"