Manatee is the platform which interprets and runs flows. It provides all the functionality necessary for interacting with applications and a number of modules for doing things like talking to HTTP servers, parsing CSV files etc.

User interface

The primary interface is the flow launching menu which you get to by right-clicking in an attached application.

Url commands

Manatee has the ability to respond to special hyperlinks being activated. This can be used for directly launching flows or for altering one or more Manatee settings.

This works by registering a special url scheme while specifying that the Manatee client is responsible for handling such links. Much like how mailto links are oftentimes handled by Outlook or some other email client.

A benefit of this technique is that it doesn’t require Manatee to be running beforehand. If Manatee isn’t running, it will be started and then presented with the command specified in the activation url. If there is already a Manatee running when the url is activated, that Manatee will process the url and continue to run (unless instructed otherwise by the url).

Example use cases

• Allowing a user to start a flow from a desktop shortcut
• Helping a user change a Manatee setting by providing a link in an email or on an intranet page, thus lowering the technical barrier
• A flow developer may use desktop shortcuts for easily switching between the production groups TESTING and PRODUCTION (restarting Manatee automatically after each change)
• Third party application integration. Some applications allow hyperlinks to be configured into its menus. Such a link could be used for starting a flow.

Syntax

The urls must be constructed according to a fairly straight forward syntax as specified below.

Note that the usual rules apply regarding legal and illegal url characters. As an example, spaces must be represented as %20. The easiest way to url encode your Manatee url correctly is to use one of the many online tools for it - such as this one (opens new window).

Flow activation

The overall url syntax for flow activation is as follows: manatee:runflow/<identifier kind>/<identifier>?<flow arguments>

There are three ways of identifying a flow: by name, by subject or by its identifier. Identifying the flow by name or subject can be risky since the name isn’t guaranteed to be unique across apps. For the best results, find the automatically generated flow identifier next to its name in Cuesta and use that when constructing a flow activation url.

The format of the flow arguments are perhaps best explained with an example: manatee:runflow/withname/the%20name?some-arg=some%20value&some-other-arg=some%20other%20value&some-third-arg=a%20value.

Here the flow with the name the name would be started and receive the arguments as follows:

• some-arg = some value
• some-other-arg = some other value
• some-third-arg = a value

Changing Manatee settings

The overall url syntax for changing Manatee settings is as follows: manatee:updatesettings?<setting names and values>

As an example, changing the production group setting and enabling the flow tracer with an automatic restart afterwards would look as follows manatee:updatesettings?ProductionGroup=TESTING&ShowFlowTracer=True&restart=true.

Restarting Manatee

The special pseudo-setting of restart=true will cause Manatee to restart after processing all the actual settings in the url.

Enable/Disable the feature

The following Manatee settings affect this feature: EnableUrlCommands, ForceUnregisteringOfUrlCommands.

EnableUrlCommands

When set to true, Manatee will process url commands as described in this chapter. When set to false, all url commands are ignored. Url activation may still start Manatee, but none of the commands embedded in the url will be carried out.

ForceUnregisteringOfUrlCommands

When Manatee starts up, it verifies that the Windows registry has correct information regarding Manatee as the handler of manatee: urls. A corner case is that Manatee is registered to handle such urls, but EnableUrlCommands is set to False. Manatee will then attempt to unregister itself as the url handler. This requires administrative privileges, so it may be undesirable for end users to be presented with a Windows privilege escalation prompt. To avoid this scenario, ForceUnregisteringOfUrlCommands can be set to False (its default value). The Windows url handler registration will then remain in place, but Manatee will ignore any and all url commands.

Per user install

Per-machine installs are carried out by an administrator and so has the required privileges to register Manatee as the handler of manatee: urls. Self-updating per-user installers run without administrative privileges and so are unable to do this. When EnableUrlCommands is set to True, it is expected for Manatee to attempt to carry out the url handler registration during startup.

In this scenario the user will be prompted for the required elevation of privileges. This is generally undesirable for end-user Manatee operations. The solution is to either set EnableUrlCommands to False or use the per-machine .msi installer in stead of the per-user installer.