Creating new profiles

The Desktop agent only see events from processes it's configured to monitor, create a dummy rule that only contains the processName and events=”all”, this will enable the monitoring of the selected application.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<View timeout="180" name="Dummy" revision="1">
   <Monitor>
      <processName value="outlook" limit="processId" disabled_events="" />
   </Monitor>
</View>

Create a new folder under Profiles called Test and place the dummy rule there. (Only files in the Profiles root directory is deleted/synched with the UXM collector at every restart and 60 minutes sync)

Restart the “UXM Desktop Agent” service so it loads the new Profiles, you should now be able to see events from the process under %PROGRAMDATA%\MCG\UXM PC Agent\Logs\PCAgentUI.exe_{SessionID}.log, when you click around the the monitored application.

Finding events

Logger level has to be set to debug mode in C:\Program Files\MCG\UXM PC Agent\PCAgentUI.properties to see events in the logfiles which we can create rules from.

The file %PROGRAMDATA%\MCG\UXM PC Agent\Logs\PCAgentUI.exe_{SessionID}.log contains the events from the monitored applications.

You can use Notepad++ and set Language to JSON or Lua to get color highlighting.

Try to perform the actions in the program you want to create rules on and look for good start/complete events that happens every time.

Remember that you can use Mouse/Keyboard and Hotkeys in many application, we need to create rules for these combinations.

Also, copy the Start events to the Incomplete events, so a rule stops monitoring if the same event occurs again. The PC Agent only measure the last action (if a user for example clicks 5 times on New Email), the events would be mixed together, making it impossible to monitor each click and correlate it with the end events.

Creating the XML monitoring profile

The profile has to consist of events that Starts, Stops or Invalidates the measurement, like the following example:

A dummy example is placed under C:\Program Files\MCG\UXM Desktop Agent\Profiles\Examples and rules for standard application like Outlook, Word, Excel, Navision and Dynamics AX can be downloaded from the download section.

View

Attribute	Description
timeout	How many seconds do we wait from we started measuring to we see a Complete event. Monitor Rule will go to Incomplete state if the timeout value is reached.
name	Name that the monitor rule is linked to inside the UXM system, the name will automatically be created as a new View. You can have multiple monitor rules that stores data under the same view. (For multiple languages support for example)
revision	Increased by 1 each time the monitor rule is changed. Is for detecting which monitor rule is the newest.
debug	?

Monitor

Used to control which program that we inject/measure on.

ProcessName

Attribute	Description
value	Name of the process we want to monitor, also works with .exe. Example: outlook or outlook.exe.
match	Requires UXM Desktop Agent 2023.01.31 Can be any of the following, will take the process name and match with the value attribute. equals: process name has to be equal to value (Case insensitive), this is the default value if this attribute is not provided or empty/invalid. contains: True if process name contains the value (Case insensitive) regex: Value can be a regular expression that matches process name.
limit	Some programs like Google spawns multiple processes in the background (Each tab is a process), the makes the profiles fail because the only listen to events from the same processId, you can alter the PC Agent to limit by processName. Warning: Setting to none could cause a high overhead if you have many profiles and events, because all events are compared to all profiles. Can be one of the following: processId processName none Default is processId.
disabled_events	Comma separated list over events to disable. Disable hooking into events that are send to frequently and stalling/delaying the measurement. Is used for IE browser monitoring where ObjectValueChange can be send 500 times per click and delay events with 40 seconds. Can be one of the following: ObjectNameChange ObjectValueChange ObjectFocus Example: ObjectNameChange,ObjectValueChange

ProcessPath (Optional, new in version 2019.5.16)

Attribute	Description
match	contains (Only contains is supported)
value	Path of the process we want to monitor. Is used if program can be launched from multiple paths like: C:\Program Files\MyProgram - Prod\ C:\Program Files\MyProgram - UAT\ Example: \MyProgram - UAT\

StateRuleGroups

Contains rules for starting a monitor and rules for when is reaches the complete/incomplete or error state.

StateRuleGroup

Attribute	Description
to	The Statemachine will change state to: start complete incomplete failed
match	any: Change state if any of the sub rules matches. all/and: Do we support this ??

Rule

Attribute	Description
id	ID that makes it easier to debug and find the rule inside the log files. start rules uses 1xx complete rules uses 2xx incomplete rules uses 3xx failed rules uses 4xx
type	Event type to match on, can be any of the following: // Process events. processLaunch processExit // Mouse events. LeftMouseClick LeftMouseDoubleClick RightMouseClick // Keyboard events. KeyPress // UX/MSAA events. ObjectNameChange ObjectValueChange ObjectShow ObjectHide ObjectFocus // PropertyChanged events. ChildAdded ChildRemoved ChildrenInvalidated ChildrenBulkAdded ChildrenBulkRemoved ChildrenReordered StateChange LocationChange
debug	Set to true to debug this rule. Debugging it will write more information in the log files when we compare each value in the rule. It will also send all events to the UXM collector, so we can troubleshoot rules with high/low response times.

RuleCondition

Attribute	Description
property	Can be any of the following, will take the event value of property and match to the value field in the XML RuleCondition: role name value eventClass firstNonChildWindowTitle firstNonChildWindowClass // Keyboard properties. vkey keyCode (New in version 2021.06.22) modifier // Process parameters. processName (New in version 2021.06.22) // Parent properties. parentRole parentName parentValue
match	Can be any of the following, will take the value from property and match with the value attribute. equals: property has to equal value. (Case insensitive compare) contains: True if property contains the value. regex: Value can be a regular expression that matches property.
matchBy	Alters the match validation, can be any of the following: not: Match is inverted/NOTed, is used when you want to avoid complex regexes. For example start measuring on LeftMouseClick if name contains a value:
value	The property value to match via the match type (equals \| contains \| regex)

Regex examples

Action	Character	Example
Contains	.*	.Outlook.
Escape special characters	\	.Untitled - Message \(.
Starts with	^	^Calendar.*
Ends with	$	.* - Outlook$

OR / AND rules

You can create complete rules by using AND OR and matchBy=”not”.

The following rule is matches when:

Ctrl + N is pressed.
eventClass equals _WwG, OutlookGrid or NetUIHWND.
Windows title contains Outlook and doesn’t start with Calendar, Contacts, Folders, Notes or To-Do List.

Testing rules

The Desktop Monitor can load profiles and check when their rules is started and completed.

Launch it from C:\Program Files\MCG\UXM Desktop Agent\Recorder\DesktopMonitor.exe

Click "Load Profiles" and select the profile directory C:\Program Files\MCG\UXM Desktop Agent\Profiles

Your profiles and the profiles loaded from the UXM Collector will be displayed, press "Start monitoring Log Folder" to see live statistics on when profile rules starts, completes and is going to incomplete state.

Perform the transaction you are trying to record and validate that it Starts and Completes and that it's "Duration (ms)" is correct.

Debugging rules

Logger level has to be set to debug in C:\Program Files\MCG\UXM Desktop Agent\PCAgentUI.properties to see debug events in the logfiles.

Update the monitor rule XML file by setting Rule -> debug=”true”, place the XML file inside your Test folder or upload to MCG UXM Splunk controller, then restart the UXM Desktop Agent service.

Try to create the event/scenario and view the logfile under %PROGRAMDATA%\MCG\UXM PC Agent\Logs\PCAgentUI.exe_{SessionID}.log.

The logfile will now show each RuleCondition and if it matches with the event, it will also show if the AND/OR groups matched.