QPR TaskRecorder: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
mNo edit summary
 
(32 intermediate revisions by one other user not shown)
Line 1: Line 1:
QPR TaskRecorder is a desktop application, that records actions done by the user. The actions can be for example mouse clicks, key presses, UI elements focusing, button clicks, selections and text input.
QPR TaskRecorder is a desktop application that records actions done by the user when interacting with applications. The actions can be for example mouse clicks, key presses, UI elements focuses, button clicks, element selections and text input. QPR TaskRecorder collects the UI events to a CSV file, which can be uploaded to QPR ProcessAnalyzer for further analysis.
 
QPR TaskRecorder is an essential software tool part of ''task mining'', which is a methodology and technologies to collect and analyze actions done by users when executing business processes. Traditional ''process mining'' is able to use data stored to different information systems, which in many situations is not enough to analyze all aspects of the business process. This is because some business processes don't use dedicated information systems at all, but the process is based on for example Excel documents or email communication. In addition, even when information systems are used, they may not record time used for the entire user interaction from start to end, limiting what kind of analyses are possible.
 
QPR TaskRecorder is able to collect also those activities that the traditional process mining cannot record, and give a more complete picture of the business process. In practice, the events collected by QPR TaskRecorder can complement the existing process mining models by adding more detailed types of events or giving additional metadata for the existing events.


== QPR TaskRecorder installation ==
== QPR TaskRecorder installation ==
QPR TaskRecorder is a desktop application that can be run in Windows operating systems.
QPR TaskRecorder is a desktop application that can be run in Windows operating systems. QPR TaskRecorder can be installed as follows:


QPR TaskRecorder is installed as follows:
# Ask the QPR TaskRecorder installation package from your QPR representative.
# Extract the package into a suitable location, e.g., C:\QPR TaskRecorder. (The package contains two files: ''TaskRecorder.exe'' and ''appsettings.json''.)
# If needed, change settings in the ''appsettings.json'', as instructed in the [[QPR TaskRecorder#QPR TaskRecorder configuration|QPR TaskRecorder configuration]] section. This step is optional, as in most cases QPR TaskRecorder works with the default settings.
# If you want to run QPR TaskRecorder automatically when Windows starts, right click the ''TaskRecorder.exe'' and select ''Create shortcut''. Press the Windows logo key + R, type ''shell:startup'', then select ''OK''. This opens the Startup folder. Move the shortcut to the Startup folder.
# You are ready to start [[QPR TaskRecorder#Using QPR TaskRecorder|using QPR TaskRecorder]]!


# Download the QPR TaskRecorder in the [[QPR_ProcessAnalyzer_Downloads|downloads page]].
== QPR TaskRecorder configuration ==
# Extract the zip package to a suitable location, for example: C:\Program Files\QPR TaskRecorder.
QPR TaskRecorder has configuration file '''appsettings.json''' available in the QPR TaskRecorder installation folder. The file has the following settings:
# Configure the QPR TaskRecorder configuration file, as instructed in the . This step is optional, as QPR TaskRecorder works with the default settings.
* '''OutputFile''': The CSV file containing the recorded UI events. If this setting is not defined, the CSV file is stored to the user's '''Documents''' folder.
# You are ready to start using [[QPR TaskRecorder#Using QPR TaskRecorder|QPR TaskRecorder]]!.
* '''LogFile''': Locations of the QPR TaskRecorder file log, used for detailed application information and error message. When this setting is set, the application logging is enabled. When not set, the application logging is not done. See more information about the [[QPR TaskRecorder#QPR TaskRecorder file log|QPR TaskRecorder file log]].


== QPR TaskRecorder configuration ==
Note that as the configuration file format is json, backslashes (\) used in the OutputFile and LogFile settings must be escaped with double backslashes (\\), e.g.,
QPR TaskRecorder has configuration file '''appsettings.json''' containing the following settings:
<pre>
* '''OutputFile''': The CSV file containing the recorded events. If the setting is not defined, the CSV file is created in the user's own '''Documents''' folder.
{
* '''LogFile''': Application log file of QPR TaskRecorder. When set, the application logging is enabled. When not set, no application logging is done.
  "OutputFile": "C:\\Logs\\RecordedUIEvents.csv",
  "LogFile": "C:\\Logs\\QPRTaskRecorderLog.txt"
}
</pre>


== Using QPR TaskRecorder==
== Using QPR TaskRecorder==
QPR TaskRecorder is started by double clicking the '''TaskRecorder.exe''' file.
You can start QPR TaskRecorder by double clicking the '''TaskRecorder.exe''' file in the installation folder.
 
The main dialog of QPR TaskRecorder contains a table of all currently open applications. You can choose which applications are recorded by clicking the checkboxes in the rows. Each application is listed only ones, and when enabled, all running instances of the application are recorded. For example, there may several Word files open at the same time and all are recorded.
 
When open, QPR TaskRecorder is active and records the selected applications. If there is an error situation, e.g., the CSV file is reserved by another application, the '''Status''' field shows more details.


The main dialog of QPR TaskRecorder contains a table of all currently open applications. You can choose which applications are recorded by clicking the checkboxes next to the application name. Each application is listed only ones, and when enabled, all running instances of the application are recorded. E.g. there may several Word files open at the same time and all are recorded.
User can add manual annotations during the recording to help analyzing the recorded UI events. Annotations are added by writing the text to the '''Annotation''' textbox and clicking the '''Save annotation''' button.


When open, QPR TaskRecorder is all the time active and records the selected applications. If there is an error situation, e.g., the CSV file is reserved by another application, the '''Status''' field shows the situation.
Recording is stopped when closing QPR TaskRecorder by clicking the '''X''' button in the top right.


User can add manual annotations during the task recording to help analyzing the recorded UI events log. Annotations are added by writing a text for the annotation in the '''Annotation''' textbox and clicking the '''Save annotation''' button.
See in the [[QPR TaskRecorder#Recorded CSV file|Recorded CSV file]] section how to upload the UI events log to QPR ProcessAnalyzer.


Recording is stopped by closing QPR TaskRecorder in the Close button in the top right.
Notes:


== Recorded UI events ==
* When QPR TaskRecorder is running with user privileges, it's not able to record applications that have been started as administrator privileges.
* The recorded applications is identified by their full path (folder path + executable file name), so different applications that have same file name are not mixed.
 
== Recorded UI event types ==
QPR TaskRecorder is able to record the following types of UI events:
QPR TaskRecorder is able to record the following types of UI events:
{| class="wikitable"
{| class="wikitable"
!'''Column name'''
!'''UI event type'''
!'''Description'''
!'''Description'''
|-
|-
||FOCUS_ENTER
||FOCUS_ENTER
||Event is recorded for the new focused control when focus changes.
||Event is recorded when a UI control gets the focus.
|-
|-
||FOCUS_LEAVE
||FOCUS_LEAVE
||Event is recorded for the previously focused control when focus changes.
||Event is recorded when a UI control loses the focus.
|-
|-
||WM_LBUTTONDOWN
||WM_LBUTTONDOWN
||Event is recorded when the left mouse button goes down.
||Event is recorded when the left mouse button is pressed down.
|-
|-
||WM_LBUTTONUP
||WM_LBUTTONUP
||Event is recorded when the left mouse button goes up.
||Event is recorded when the left mouse button is released.
|-
|-
||WM_RBUTTONDOWN
||WM_RBUTTONDOWN
||Event is recorded when the right mouse button goes down.
||Event is recorded when the right mouse button is pressed down.
|-
|-
||WM_RBUTTONUP
||WM_RBUTTONUP
||Event is recorded when the right mouse button goes up.
||Event is recorded when the right mouse button is released.
|-
|-
||WM_KEYDOWN
||WM_KEYDOWN
||Event is recorded when user presses a key on the keyboard. If the focused control is a password control, these types of events are not recorded.
||Event is recorded when user presses a key on the keyboard. If the focused control is a password control, the WM_KEYDOWN events are not recorded.
|-
|-
||USER_ANNOTATION
||USER_ANNOTATION
||User annotation event occurs when user creates an annotation event using the QPR TaskRecorder user interface.
||User annotation event occurs when user creates an annotation using the QPR TaskRecorder user interface.
|-
|-
||CONFIGURATION
||CONFIGURATION
Line 61: Line 79:
|}
|}


== Recorded tasks CSV ==
== Recorded CSV file ==
The user actions are recorded to a CSV file, that is stored to the user own '''Documents''' (by default when no other location is set) or a some other location user has specified. The default name of the CSV file is '''taskrecorder.csv'''. The CSV file can be uploaded to QPR ProcessAnalyzer for the analysis like any [[Importing_Data_to_Datatable_from_CSV_File|CSV file]].
User actions are recorded to a CSV file, that is stored in the user's '''Documents''' folder by default, when no other location is set. Otherwise the CSV file is stored to the specified location. The default name of the CSV file is '''taskrecorder.csv''', used when no other file location is specified.
 
The CSV file can be uploaded to QPR ProcessAnalyzer for analysis using the [[Importing_Data_to_Datatable_from_CSV_File|CSV file import]]. After uploading the file to QPR ProcessAnalyzer, it's recommended to rename the file or delete it, so that QPR TaskRecorder will start collecting events to a new file. This is to keep the uploaded and not yet uploaded UI events in separate files to avoid importing same UI events twice.


The CSV file has the following columns:
The CSV file has the following columns:
Line 70: Line 90:
|-
|-
||TimeStamp
||TimeStamp
||This information is stored for all types of events.
||The precise time of the UI event. Note that the user workstation clock is used, so this timestamp relies on the preciseness of the workstation clock. This information is stored for all types of events.
|-
|-
||UserName
||UserName
||GUID identifying the user performing the tasks. GUID is used instead of real user name to anonymize the real user. QPR TaskRecorder generates this GUID if it hasn't previously been done for this installation. This information is stored for all types of events.
||Windows login name of the user performing the tasks. This information is stored for all types of events.
|-
|-
||SessionId
||SessionId
||GUID identifying the recording session, which starts when QPR TaskRecorder starts and ends when QPR TaskRecorder is closed. This information is stored for all types of events.
||GUID identifying the recording session, which starts when QPR TaskRecorder is started and ends when QPR TaskRecorder is closed. This information is stored for all types of events.
|-
|-
||EventType
||EventType
||This information is stored for all types of events.
||Type of the UI event. For more information, see [[QPR TaskRecorder#Recorded UI events|Recorded UI events]]. This information is stored for all types of events.
|-
|-
||MouseX
||MouseX
Line 91: Line 111:
|-
|-
||Key
||Key
||For the WM_KEYDOWN events, the virtual key code of the pressed key.
||For the WM_KEYDOWN events, the virtual key code of the pressed key. More information about the virtual key codes: https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes.
|-
|-
||ModifierKeys
||ModifierKeys
Line 127: Line 147:
|-
|-
||ElementHierarchy
||ElementHierarchy
||Control hierarchy of the current application. The value is stored as JSON.
||UI control hierarchy of the recorded application at the time the UI event is recorded. The value is stored as JSON.
|}
|}
== Anonymized user id ==
User performing the tasks is identified by an anonymized user id, so persons analyzing the task log cannot identify the actual user based on the user id. When QPR TaskRecorder starts, it checks if the settings file exists in the user's application data folder, and the settings file contains user id. If the user id does not exist, a new GUID is created and saved to the user settings file.


== QPR TaskRecorder file log ==
== QPR TaskRecorder file log ==
QPR TaskRecorder writes a file log of its operation. The file log contains information about QPR TaskRecorder application functionality and application errors. Note that the file log is a different file than the recorded UI events CSV file. The location of the file log file is set in the QPR TaskRecorder [[QPR TaskRecorder#QPR TaskRecorder configuration|configuration file]]. If the location is not set, no logging is done.
QPR TaskRecorder writes a file log of its operation. The file log contains information about QPR TaskRecorder application functionality and application errors. Note that the file log is a different file than the recorded UI events CSV file. The location of the file log file is set in the QPR TaskRecorder [[QPR TaskRecorder#QPR TaskRecorder configuration|configuration file]]. If the location is not set, no logging is done.

Latest revision as of 09:09, 11 May 2022

QPR TaskRecorder is a desktop application that records actions done by the user when interacting with applications. The actions can be for example mouse clicks, key presses, UI elements focuses, button clicks, element selections and text input. QPR TaskRecorder collects the UI events to a CSV file, which can be uploaded to QPR ProcessAnalyzer for further analysis.

QPR TaskRecorder is an essential software tool part of task mining, which is a methodology and technologies to collect and analyze actions done by users when executing business processes. Traditional process mining is able to use data stored to different information systems, which in many situations is not enough to analyze all aspects of the business process. This is because some business processes don't use dedicated information systems at all, but the process is based on for example Excel documents or email communication. In addition, even when information systems are used, they may not record time used for the entire user interaction from start to end, limiting what kind of analyses are possible.

QPR TaskRecorder is able to collect also those activities that the traditional process mining cannot record, and give a more complete picture of the business process. In practice, the events collected by QPR TaskRecorder can complement the existing process mining models by adding more detailed types of events or giving additional metadata for the existing events.

QPR TaskRecorder installation

QPR TaskRecorder is a desktop application that can be run in Windows operating systems. QPR TaskRecorder can be installed as follows:

  1. Ask the QPR TaskRecorder installation package from your QPR representative.
  2. Extract the package into a suitable location, e.g., C:\QPR TaskRecorder. (The package contains two files: TaskRecorder.exe and appsettings.json.)
  3. If needed, change settings in the appsettings.json, as instructed in the QPR TaskRecorder configuration section. This step is optional, as in most cases QPR TaskRecorder works with the default settings.
  4. If you want to run QPR TaskRecorder automatically when Windows starts, right click the TaskRecorder.exe and select Create shortcut. Press the Windows logo key + R, type shell:startup, then select OK. This opens the Startup folder. Move the shortcut to the Startup folder.
  5. You are ready to start using QPR TaskRecorder!

QPR TaskRecorder configuration

QPR TaskRecorder has configuration file appsettings.json available in the QPR TaskRecorder installation folder. The file has the following settings:

  • OutputFile: The CSV file containing the recorded UI events. If this setting is not defined, the CSV file is stored to the user's Documents folder.
  • LogFile: Locations of the QPR TaskRecorder file log, used for detailed application information and error message. When this setting is set, the application logging is enabled. When not set, the application logging is not done. See more information about the QPR TaskRecorder file log.

Note that as the configuration file format is json, backslashes (\) used in the OutputFile and LogFile settings must be escaped with double backslashes (\\), e.g.,

{
  "OutputFile": "C:\\Logs\\RecordedUIEvents.csv",
  "LogFile": "C:\\Logs\\QPRTaskRecorderLog.txt" 
}

Using QPR TaskRecorder

You can start QPR TaskRecorder by double clicking the TaskRecorder.exe file in the installation folder.

The main dialog of QPR TaskRecorder contains a table of all currently open applications. You can choose which applications are recorded by clicking the checkboxes in the rows. Each application is listed only ones, and when enabled, all running instances of the application are recorded. For example, there may several Word files open at the same time and all are recorded.

When open, QPR TaskRecorder is active and records the selected applications. If there is an error situation, e.g., the CSV file is reserved by another application, the Status field shows more details.

User can add manual annotations during the recording to help analyzing the recorded UI events. Annotations are added by writing the text to the Annotation textbox and clicking the Save annotation button.

Recording is stopped when closing QPR TaskRecorder by clicking the X button in the top right.

See in the Recorded CSV file section how to upload the UI events log to QPR ProcessAnalyzer.

Notes:

  • When QPR TaskRecorder is running with user privileges, it's not able to record applications that have been started as administrator privileges.
  • The recorded applications is identified by their full path (folder path + executable file name), so different applications that have same file name are not mixed.

Recorded UI event types

QPR TaskRecorder is able to record the following types of UI events:

UI event type Description
FOCUS_ENTER Event is recorded when a UI control gets the focus.
FOCUS_LEAVE Event is recorded when a UI control loses the focus.
WM_LBUTTONDOWN Event is recorded when the left mouse button is pressed down.
WM_LBUTTONUP Event is recorded when the left mouse button is released.
WM_RBUTTONDOWN Event is recorded when the right mouse button is pressed down.
WM_RBUTTONUP Event is recorded when the right mouse button is released.
WM_KEYDOWN Event is recorded when user presses a key on the keyboard. If the focused control is a password control, the WM_KEYDOWN events are not recorded.
USER_ANNOTATION User annotation event occurs when user creates an annotation using the QPR TaskRecorder user interface.
CONFIGURATION Configuration change event occurs when user changes the recorded applications.

Recorded CSV file

User actions are recorded to a CSV file, that is stored in the user's Documents folder by default, when no other location is set. Otherwise the CSV file is stored to the specified location. The default name of the CSV file is taskrecorder.csv, used when no other file location is specified.

The CSV file can be uploaded to QPR ProcessAnalyzer for analysis using the CSV file import. After uploading the file to QPR ProcessAnalyzer, it's recommended to rename the file or delete it, so that QPR TaskRecorder will start collecting events to a new file. This is to keep the uploaded and not yet uploaded UI events in separate files to avoid importing same UI events twice.

The CSV file has the following columns:

Column name Description
TimeStamp The precise time of the UI event. Note that the user workstation clock is used, so this timestamp relies on the preciseness of the workstation clock. This information is stored for all types of events.
UserName Windows login name of the user performing the tasks. This information is stored for all types of events.
SessionId GUID identifying the recording session, which starts when QPR TaskRecorder is started and ends when QPR TaskRecorder is closed. This information is stored for all types of events.
EventType Type of the UI event. For more information, see Recorded UI events. This information is stored for all types of events.
MouseX For the mouse events, horizontal position of the mouse cursor, i.e. distance from the left border of the screen.
MouseY For the mouse events, vertical position of the mouse cursor, i.e. distance from the top border of the screen.
KeyCode For the WM_KEYDOWN events, the key code of the pressed key.
Key For the WM_KEYDOWN events, the virtual key code of the pressed key. More information about the virtual key codes: https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes.
ModifierKeys For the WM_KEYDOWN events, the modifier keys pressed at the time of the key press (shift, ctrl, alt, windows).
ProcessName Name of the application (executable file name).
ClassName Class of the UI control.
ControlType Type of the UI control.
Name Name of the UI control.
Value Value or text of the UI control.
LabelName Name of the UI control label.
ElementX Horizontal position of the interacted UI control, i.e. distance between the left border of the UI control from the left border of the screen.
ElementY Vertical position of the interacted UI control, i.e. distance between the top border of the UI control from the top border of the screen.
ElementWidth Width of the interacted UI control.
ElementHeight Height of the interacted UI control.
ElementHierarchy UI control hierarchy of the recorded application at the time the UI event is recorded. The value is stored as JSON.

QPR TaskRecorder file log

QPR TaskRecorder writes a file log of its operation. The file log contains information about QPR TaskRecorder application functionality and application errors. Note that the file log is a different file than the recorded UI events CSV file. The location of the file log file is set in the QPR TaskRecorder configuration file. If the location is not set, no logging is done.