Legacy Native Plugin

This plugin provides a driver compatible with the original native driver built into Manatee up to and including v1.29.

It mainly serves to provide backwards compatibility for existing native applications when Manatee is upgraded from v1.29 to v2.0. At the 2.0 level, native applications will start using this plugin automatically since the Manatee built-in driver was changed for the 2.0 release.

Example use cases

• When you run Manatee 2.0 and your flows and fields were made for the older native driver
• In the unexpected event that some specific piece of automation works better under the old driver

Manatee 2.0

Upon the rollout of Manatee 2.0, the default built-in native driver changes to the new FlaUI driver. In order to avoid breaking existing native app automations when this happens, the responsibility of handling such apps is handed over to the LegacyNative plugin. Make sure to take steps to ensure that the LegacyNative plugin is running on Manatees that need it for running the existing native app automation.

In Cuesta 1.14 and Cuesta 1.15, this same driver is simply called Native as it is the default driver for native Windows applications up to and including Manatee v1.29.

In Cuesta 1.16, it is shown as Legacy Native to indicate that as of Manatee v2.0, it is no longer the recommended option for new Windows applications to be automated.

Migration case study

In the following, we will show how to migrate an existing production app from the old native driver in Manatee 1.29/1.31 to the new and improved FlaUI driver present in Manatee 2.0.

For the purposes of this example, the app is the standard Windows Notepad application, seen here in Cuesta v1.15 before the migration:

Protect your users!

If the app is in production and in active use, we need to make a copy of the app first and do our testing there (the copy button in the app settings page in Cuesta). Be mindful of any changes done to flows/fields under the original app while this work is ongoing.

Two strategies

There are two overall strategies for migrating the app. Each with its own pros and cons:

1. Migrate to FlaUI: If the app is small and simple, or if you have the resources to test all fields and flows, you can switch to the new FlaUI driver. This way you avoid the overhead of handling plugins in Manatee 2.0.
2. Stay on Legacy Native: Switching to the new driver requires thorough testing of all fields and flows. If the app is large and complex, this can be a daunting task. In this case, it might be better to stay on the Legacy Native driver for the time being. Staying on the legacy driver in Manatee 2.0 requires loading a plugin in all running Manatees (LegacyNativePlugin).

Strategy 1: Migrate to FlaUI

This strategy can be started before or after the Manatee upgrade.

Starting before the Manatee upgrade involves installing the FlaUINativePlugin plugin in Manatee 1.29/1.31 and testing the app with the plugin’s provided driver. This way you can decide when to do the migration work independently ahead of the Manatee upgrade schedule.

If you create new Native apps on Manatee 1.29/1.31 after reading this, it would be wise to use the FlaUINativePlugin driver, so that you are already using the new driver. This should give you a very easy migration when you roll out Manatee 2.0.

Starting after the Manatee upgrade means you need early access to Manatee 2.0, so you can test the app with its built-in FlaUI driver before your users upgrade.

Switching to the FlaUI driver

Whether you use the plugin FlaUI driver or the one that ships with Manatee 2.0, you need to switch your app to use the new driver. This is done in the app settings page in Cuesta:

Selecting the plugin driver:

Read the section below on how to install the FlaUINativePlugin plugin and register its driver.

Selecting the built-in driver:

Testing the app on the new driver

After switching the app to the new driver, you need to test all flows and fields to make sure they work as expected. Most fields are expected to work as is, but some may need adjustments. The field finder should be of use in this endeavor.

There may be minor differences in the data available in the output from the .inspect() command, so that is something to look out for.

Installing a driver plugin

At this point we will take a slight detour to learn how to install and start a Manatee plugin. Manatee plugins are most easily installed from a flow on a headless app as in the following screenshot:

This downloads, unpacks, verifies, loads and starts the plugin in one go. The plugin is now available

Here is the FlaUINativePlugin code for simpler copy/pasting:

  try {
    Plugin.start('FlaUINativePlugin', 'v1.0.13', {});
    Notification.show('n1', 'Plugin started', 'FlaUINativePlugin v1.0.13');
  } catch (e) {
    Notification.show('n1', 'Plugin failed to start', e && (e.message || e));
  }

Unsurprisingly, the LegacyNativePlugin code is similar:

  try {
    Plugin.start('LegacyNativePlugin', 'v1.0.1', {});
    Notification.show('n1', 'Plugin started', 'LegacyNativePlugin v1.0.1');
  } catch (e) {
    Notification.show('n1', 'Plugin failed to start', e && (e.message || e));
  }

Automatic loading

To have the plugin loaded automatically, add a Manatee started trigger to the flow. The benefit of having the flow on a headless app is that the flow can run without having to attach an app first.

Registering the driver

After starting the plugin, you need to register the driver with Cuesta. The registration is done via the Manatee right click menu as in shown in this screenshot:

This makes the driver selectable in the app settings page in Cuesta. The procedure for the Legacy Native driver is the same.

Note that this step only needs to be done once to make the driver selectable in Cuesta. Accidentally registering the same driver multiple times is fine.

Strategy 2: Staying on Legacy Native

For this strategy, you start with a running Manatee 2.0 and Cuesta 2.0. Make sure you get early access to these so you can prepare the migration before your users are upgraded to Manatee 2.0. The app won’t be able to attach since Manatee 2.0 does not ship with the required Native driver. You will see a notification like the following:

There is no migration of the app configuration itself in this case, but you need to follow the steps above to load the LegacyNativePlugin in all running instances of Manatee 2.0. This way, the app can attach and run as before.

The last step is to switch the app to use the Legacy Native driver in the app settings page in Cuesta:

At this point, the app should attach and work as before for Manatees with the plugin loaded.

Releases

v0.0.25

Initial (public) release.

v0.1.0

Switched nuget source to Gitlab. Bumped PluginApi to v1.16.5 (published from Manatee v1.29)

v1.0.3

Updated for compatibility with Manatee v2.0.0.