Creating plugins

A TM Agent plugin is a simple C# class which inherits from AgentPlugin class available in the TaskMining.Agent.Plugin.dll file. You can find this DLL file in your TM Agent installation directory (for example, C:\Program Files\IBM Task Mining Agent\TaskMining.Agent.Plugin.dll).

Create a plugin project
To create a plugin project, you can use any of the following methods:

Create project from IBM Task Mining Agent Plugin template available in Visual Studio 2022.
Create a net7.0-windows project with TaskMining.Agent.Plugin.dll reference.

An example for a plugin project is shown in the following code snippet. In this example, HintPath specifies the path to the TM Agent installation directory.


<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net7.0-windows</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <Reference Include="TaskMining.Agent.Plugin">
            <HintPath>C:\Program Files\IBM Task Mining Agent\TaskMining.Agent.Plugin.dll</HintPath>
        </Reference>
    </ItemGroup>

</Project>

Create an entry point.
After creating the project, you must create an entry point for the plugin. This is the class that inherits from AgentPlugin class.

⚠ Important: You must specify the processName in the base constructor in AgentPlugin class.

Example:
```
using TaskMining.Agent.Plugin;

namespace TaskMining.Notepad.Plugin
{
    public class NotepadPlugin : AgentPlugin
    {
        public NotepadPlugin()
            : base("notepad")
        {

        }
    }
}
```
In this example, the plugin class is NotepadPlugin and the processName is notepad.

Enhance hooks and watch properties.
By default, TM Agent captures only the following events:

Mouse: Click
Keyboard: Tab, Return, Ctrl+C, Ctrl+V

TM Agent plugins adds four more properties to this list to enhance keyboard hooks.

Property	Description
WatchAltKeys	Enable or disable keyboard ALT keys events. By default, this is set to `false`.
WatchCtrlKeys	Enable or disable keyboard Control keys events. By default, this is set to `false`.
WatchFunctionKeys	Enable or disable keyboard Function keys events. By default, this is set to `false`.
WatchNumberKeys	Enable or disable keyboard Number keys events. By default, this is set to `false`.

Modify mouse and keyboard event recording.
To intercept any event recorded by the TM Agent, you can use two events, MouseDown and KeyboardDown. Both of these events have specific EventArgs (namely, PluginMouseEventArgs and PluginKeyboardEventArgs) with properties that allows to understand, modify, or cancel the activity recorded.

These two EventArgs share the following three properties that you can use to edit the tasks in Task Mining.

Property	Description
Titles	This property gets or sets titles (Page & URL Titles) of events.
Selector	This property gets or sets selector (Task name selector) of events.
Cancel	This property gets or sets a value to indicate whether the event should be canceled.

Project Task Properties

Example:

using TaskMining.Agent.Plugin;

namespace TaskMining.Notepad.Plugin
{
    public class NotepadPlugin : AgentPlugin
    {
        public NotepadPlugin() 
          : base("Notepad")
        {
         this.WatchFunctionKeys = true;
         this.KeyboardDown += NotepadPlugin_KeyboardDown;
         this.MouseDown += NotepadPlugin_MouseDown;
        }

        private void NotepadPlugin_MouseDown(object sender, PluginMouseEventArgs args)
        {
            args.Cancel = true;
        }

        private void NotepadPlugin_KeyboardDown(object sender, PluginKeyboardEventArgs args)
        {
            if (args.Selector == "Win32[@ClassName=RichEditD2DPT][@Type=document][@Name=Text editor]")
            {
            args.Selector = "Text editor";
            }
            else
            {
            args.Cancel = true;
            }
        }
    }
}

This plugin cancels the recording of all mouse actions and permits the recording of only the keyboard events. It also specifies to rename selector to Text editor and to record all the function key events.

Using AutomationContext.
TM Agent records events when users click or press buttons on an element. This element is an AutomationElement and could be found inside PluginMouseEventArgs and PluginKeyboardEventArgs. AgentPlugin also allows to access any AutomationElement present on screen by using AutomationContext.

Property	Description
`GetFocusedElement`	This property gets the currently focused element as an `AutomationElement`.
`GetFromPoint`	This property creates an `AutomationElement` from a given point.
`GetFromHandle`	This property creates an `AutomationElement` from a given windowshandle (HWND).

Using these properties, you can access any element present on the user screen, along with its details such as name, values, and location.

Create events.
You can use CreateActivity to create an event without waiting for MouseDown and KeyboardDown. This enables you to push any future TM tasks by just invoking it. CreateActivity could be useful for activities that are not raised directly by the user. For example, an email received from Microsoft Outlook can be intercepted and pushed to TM events by this function.

You can find more details on this from the code hints available in your IDE. For example, Visual Studio IntelliSense.

After you have completed creating and configuring your plugin, you can proceed to test and deploy the plugin.