Case Level Permissions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search

Each QPR ProcessAnalyzer model has a Configuration field containing model related settings in a JSON format. Those settings are documented in this page. When the model JSON configuration is changed, the model is dropped from the memory.

Memory Usage Settings

Memory settings can be used to manage, how long objects are kept in the memory. They affect the memory usage and user experience. The longer are the storing times, more memory is consumed, but on the other hand user perceives better performance as analyses are more likely to be found as already calculated in the memory.

Property Description

CacheUsage/ DropUnusedModelsAfter

Time after which the model that have not been used, are dropped from the memory. Defined in format HH:mm:ss or d.HH:mm:ss, for example 01:00:00 (one hour), 00:30:00 (30minutes), or 1.00:00:00 (24 hours). When an analysis is requested for a model, the last used time is updated.

If this setting is not defined, the server level default setting is used.

CacheUsage/ DropUnusedFiltersAfter

Time after which unused filter for the model, are dropped from the memory. Defined in format HH:mm:ss or d.HH:mm:ss, for example 01:00:00 (one hour), 00:30:00 (30minutes), or 1.00:00:00 (24 hours). When an analysis is requested for a model, the last used time is updated.

If this setting is not defined, the server level default setting is used.

Data in QPR ProcessAnalyzer memory, is managed in following types of objects:

Stored Object Description Dropping from memory Usual reloading time
Models All QPR ProcessAnalyzer model data, such as cases, events, event types and variations. model setting; if not defined, server setting is used. If that is not defined, a default value of 1 hour is used. slow
Filters All filtered data, including cases, events, event types and variations. model setting; if not defined, server setting is used. If that is not defined, a default value of 30 minutes is used. fast
Analysis results Results of the analysis (in tabular form). 15 minutes fast

If the server has too little memory to store all data, objects are dropped from the memory earlier than the storing times settings define. Objects are dropped from the one that has longest time from the last access. Models are not dropped due to memory shortage (i.e. only filter and analysis results are dropped), because recalculating filters and analysis results is usually faster than loading models. That's why, when trying to load more models that there is available memory in the server, an out of memory error situation may occur.

Loading Process Mining Data from ODBC Datasource

Settings

The DataSource section is used to define where the QPR ProcessAnalyzer model data is loaded. See below examples, how to construct the full JSON.

Property Description
Cases
Property Description
DataSourceType Datasource type to use, when fetching the Cases data. Currently the only supported value is odbc.
OdbcConnectionString ODBC connection string to use to fetch the Cases data. Connection strings can be found in https://www.connectionstrings.com.
OdbcQuery ODBC query to use to fetch the Cases data. Query syntax depends on the source system where the data is fetched.
Columns Column name mappings for QPR ProcessAnalyzer data model. Only supported mapping is CaseId defining the case id (case name). Example: 
{ 
  "CaseId": "SalesOrderHeaderId"
}

All unmapped columns are taken to the model as case attributes. If the fetched data doesn't contain a mapped column, the model loading fails and an error message is given.

Events
Property Description
DataSourceType Datasource type to use, when fetching the Events data. Currently the only supported value is odbc.
OdbcConnectionString ODBC connection string to use to fetch the Events data. Connection strings can be found in https://www.connectionstrings.com.
OdbcQuery ODBC query to use to fetch the Events data. Query syntax depends on the source system where the data is fetched.
Columns

Column name mappings for QPR ProcessAnalyzer data model. Supported mappings for Events are CaseId, EventType and Timestamp. Example: 

{ 
  "CaseId": "SalesOrderHeaderId",
  "EventType": "EventType",
  "Timestamp": "CreatedDate"
}

All unmapped columns are taken to the model as event attributes. If the fetched data doesn't contain a mapped column, the model loading fails and an error message is given.

Configurations examples

ODBC Driver Installation

Microsoft Access Database Engine 2016 Redistributable is software package that contains ODBC drivers for

  • Microsoft SQL Server
  • Microsoft Access (*.mdb and *.accdb) files
  • Microsoft Excel (*.xls, *.xlsx, and *.xlsb) files
  • CSV text files

The package needs to be installed in the same computer where the QPR ProcessAnalyzer Server is running. Installation instructions:

  1. Go to https://www.microsoft.com/en-us/download/details.aspx?id=54920 and click Download.
  2. Select whether to use the 32bit or 64bit (x64) version (usually it's the 64bit version).
  3. Double-click the executable file on your hard disk to start the setup program.
  4. Follow the instructions on the screen to complete the installation.

Read data from CSV file

In this example, data is loaded from CSV files located in the file system using Microsoft Access Text Driver (*.txt, *.csv) driver. Loaded files are C:\ProcessMiningData\ModelCaseAttributes.csv and C:\ProcessMiningData\ModelEventData.csv. 

{
  "DataSource": {
    "Cases": {    
      "DataSourceType": "odbc",
      "OdbcConnectionString": "Driver={Microsoft Access Text Driver (*.txt, *.csv)};DefaultDir=C:\\ProcessMiningData\\;Extensions=asc,csv,tab,txt",
      "OdbcQuery": "SELECT * FROM [ModelCaseAttributes.csv]",
      "Columns": { 
        "CaseId": "Name"
      }
    },
    "Events": {
      "DataSourceType": "odbc",
      "OdbcConnectionString": "Driver={Microsoft Access Text Driver (*.txt, *.csv)};DefaultDir=C:\\ProcessMiningData\\;Extensions=asc,csv,tab,txt",
      "OdbcQuery": "SELECT * FROM [ModelEventData.csv]",
      "Columns": { 
        "CaseId": "Case",
        "EventType": "Event Type",
        "Timestamp": "Start Time"
      }
    }
  }
}

When reading from CSV files, you may need to set the CSV file format for the ODBC driver using the Schema.ini file (more information: https://docs.microsoft.com/en-us/sql/odbc/microsoft/schema-ini-file-text-file-driver?view=sql-server-2017).

Read data from Excel file

In this example, data is loaded from a Excel file that is accessible in the file system. In this example, the loaded file is C:\ProcessMiningData\ModelData.xlsx and cases are in sheet MyCases and events in sheet MyEvents. 

{
  "DataSource": {
    "Cases": {
      "DataSourceType": "odbc",
      "OdbcConnectionString": "Driver={Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)};DBQ=C:\\ProcessMiningData\\ModelData.xlsx",
      "OdbcQuery": "SELECT * FROM [MyCases$]",
      "Columns": {
        "CaseId": "Case ID"
      }
    },
    "Events": {
      "DataSourceType": "odbc",
      "OdbcConnectionString": "Driver={Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)};DBQ=C:\\ProcessMiningData\\ModelData.xlsx",
      "OdbcQuery": "SELECT * FROM [MyEvents$]",
      "Columns": {
        "CaseId": "Case ID",
        "EventType": "Activity",
        "Timestamp": "Start Time"
      }
    }
  }
}

Read data from SQL Server table

In this example, data is loaded from an SQL Server table. In this example, the SQL Server hostname is MySQLServer and database name is MyDatabase. 

{
  "DataSource": {
    "Cases": {
    "DataSourceType": "odbc",
    "OdbcConnectionString": "Driver={SQL Server};Server=MySQLServer;DataBase=MyDatabase;Trusted_Connection=True;",
    "OdbcQuery": "SELECT CASENAME, COST, COUNTRY, PRODUCT FROM CASES_TABLE",
    "Columns": { 
      "CaseId": "CASENAME"
    }
    },
    "Events": {
      "DataSourceType": "odbc",
      "OdbcConnectionString": "Driver={SQL Server};Server=MySQLServer;DataBase=MyDatabase;Trusted_Connection=True;",
      "OdbcQuery": "SELECT CASENAME, CREATED_DATE, CREATED_BY FROM EVENT_TABLE",
      "Columns": { 
        "CaseId": "CASENAME",
        "Timestamp": "CREATED_DATE",
        "EventType": "CREATED_BY"
      }
    }
  }
}

Troubleshooting

The following error message may be encountered: System.Data.Odbc.OdbcException (0x80131937): ERROR [IM002] [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified. Probable reason is that the ODBC driver is missing or driver name is not correct. To solve the issue:

  • Check ODBC drivers is installed by running C:\Windows\System32\odbcad32.exe.
  • Check the connection string.

The following error message may be encountered: ERROR [HY024] [Microsoft][ODBC Text Driver] '(unknown)' is not a valid path. Make sure that the path name is spelled correctly and that you are connected to the server on which the file resides.. Example error when specified directory is missing:

Error when CSV file is missing: System.Data.Odbc.OdbcException (0x80131937): ERROR [42S02] [Microsoft][ODBC Text Driver] The Microsoft Access database engine could not find the object 'CaseAttributes.csv'. Make sure the object exists and that you spell its name and the path name correctly. If 'CaseAttributes.csv' is not a local object, check your network connection or contact the server administrator.

Error codes for troubleshooting: ODBC Error Codes.

If the error message mention about Case or Event attributes named as F<column number> (e.g. F10), the data might be inconsistent, as there might be different amount of columns in different rows.

Model Automatic Loading on Server Startup

QPR ProcessAnalyzer models can be loaded automatically, when QPR ProcessAnalyzer Server starts. When the model loading takes long time, it's useful to load it automatically beforehand. In the model JSON settings, when the LoadOnStartup property is set to true, the model is loaded automatically during QPR ProcessAnalyzer Server startup. The JSON configuration (that only contains that setting) is as follows: 

{
  "LoadOnStartup": true
}

Note that this setting to work, IIS configurations related to QPR ProcessAnalyzer Server installation needs to be in place.

Case Permissions

Settings

The Permissions section specifies data security restrictions for objects within the QPR ProcessAnalyzer model (i.e. limit visibility). If the Permissions section hasn't been defined, all the model data is visible to all users having GenericRead permission for the project in which the model resides (more information about roles and permissions). Permissions defined in this section, are only available when using the In-Memory core.

Property Description
Initialization Expression language expression used to make an initial calculation for all the other expressions within this same permissions context. This expression can be used to improve performance when part of the Case or EventLogKey expressions are common and thus they don't need to be calculated again for every Case separately. See the examples below of using the Initialization expression.
Case Expression language expression determining which users can see each Cases. The expression is evaluated within the context of each Case. If the evaluation results true, the Case is visible for the user. Otherwise the Case, its Events and case and event attributes are not visible. This setting implements case level security restrictions.
EventLogKey Expression language expression used to uniquely identify all the unique event logs created by case permission filters. If a cached EventLog with the same key is already in the system, that EventLog is used instead of creating a new. The new EventLog is created by applying the Case expression to filter the Cases users have rights to.

Example usecase for case permissions

Case level permissions (security control) can be implemented with the principle illustrated in the image below. Users already belong to certain groups in the user management, and cases have certain case attribute values which is part of the loaded process mining data. Additionally, the linkage between case attribute values (of a certain case attribute) and groups needs to be defined when this security feature is configured. The image below illustrates the chain between users and cases, how certain users are able to see certain cases when viewing analyses from a QPR ProcessAnalyzer model.

CasePermissions.png

Example: There are groups G1, G2 and G3. Case permissions have been set as follows:

  • group G1 can only see cases where (case attribute) Region is Dallas
  • group G2 can only see cases where Region is Austin
  • group G3 can only see cases where Region is either Austin or New York

QPR ProcessAnalyzer model contains the following cases:

Case name Region (case attribute) Groups can see
A Dallas G1
B Dallas G1
C Austin G2, G3
D New York G3
E New York G3
F New York G3

Thus, when viewing analyses, a user see that the model contains the following cases:

  • If the user belongs to group G1 only, the user can see cases A and B (2 cases)
  • If the user belongs to group G2 only, the user can see case C (1 case)
  • If the user belongs to group G3 only, the user can see cases C, D, E and F (4 cases)
  • If the user belongs to groups G1 and G2 only, the user can see cases A, B and C (3 cases)

There is no way for a user to be aware of the existence of cases that the user doesn't have rights to.

Configuration examples for case permissions

In this example, visibility of cases is limited in a way that only those users can see the cases belonging to a user group which name is same as the Region (case attribute). 

{
  "Permissions": {
    "Initialization": "Let(\"groupNames\", OrderByValue(CurrentUser.GroupNames))", 
    "Case": "Region.In(groupNames)",
    "EventLogKey": "StringJoin(\"_\", groupNames)"
  }
}

In this example, cases are only visible for users whose user name is same as the Account Manager (case attribute). 

{
  "Permissions": {
    "Initialization": "Let(\"userName\", CurrentUser.Name)", 
    "Case": "(Attribute(\"Account Manager\") == userName)",
    "EventLogKey": "CurrentUser.Id"
  }
}

In this example, cases having "Region" case attribute of "Dallas" will only be visible for users belonging to user group "GroupA" (and "New York" for group "GroupB"). 

{
  "Permissions": {
    "Initialization": "Let(\"groupNames\", CurrentUser.GroupNames)", 
    "Case": "(Region == \"Dallas\" && \"GroupA\".In(groupNames)) || (Region == \"New York\" && \"GroupB\".In(groupNames))",
    "EventLogKey": "If(\"GroupA\".In(groupNames), \"_A\", \"_\") + If(\"GroupB\".In(groupNames), \"_B\", \"_\")"
  }
}
Retrieved from "https://wiki.onqpr.com/pa/index.php?title=Case_Level_Permissions&oldid=12618"