Launching Clarify via a custom clarify:// URL
The task at hand is to be able to click on a URL (such as clarify://case/12345) and that will open case 12345 in the Clarify client.
Custom URL protocols
In Windows, you can create your own custom URL protocols, which allow you to register an application to a URL.
In my previous post, I introduced a clarify:// URL protocol. Lets see how we can make that URL trigger the Clarify Client (clarify.exe)
There’s a MSDN article that outlines the basics of doing this.
Basically, you create a registry key that maps the URL to the application.
And you’re URL will be passed to the application as a parameter (that’s the %1).
Here’s a sample registry entry for this:
Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\clarify] @="URL: Protocol handled by CustomURL" "URL Protocol"="" "CustomUrlApplication"="C:\\clarify\\11.5\\client\\ClarifyClient\\clarify.exe" "CustomUrlArguments"="\"%1\"" [HKEY_CLASSES_ROOT\clarify\DefaultIcon] @="C:\\clarify\\11.5\\client\\ClarifyClient\\clarify.exe" [HKEY_CLASSES_ROOT\clarify\shell] [HKEY_CLASSES_ROOT\clarify\shell\open] [HKEY_CLASSES_ROOT\clarify\shell\open\command] @="C:\\clarify\\11.5\\client\\ClarifyClient\\clarify.exe %1"
So, when I call a URL of clarify://something, clarify.exe will be started and the URL will be passed as a parameter. And,as I showed in my previous blog post, we can then do something with that parameter, such as displaying a certain case.
What if Clarify is already running?
If the Clarify Client is already running, we don’t want to start another instance of it. We want to use the existing application instance.
There’s additional registry sub-keys that handle this. There’s a DDEEXEC sub-key which will make a DDE request to the application. And since Clarify can handle DDE calls, we can use this.
I’ll skip the details of this for now, and return to it soon.
Working Directory
One problem I immediately ran into was that you couldn’t set the working directory. This is important for clarify.exe, as it looks for files in the working directory (such as clarify.env, speller.tlx, clfybsy.dat, cache files, etc.) And if it can’t find those, it throws up warning messages, which is sucky. So, the working directory is important.
Launcher
A little bit of web searching, and it turns out someone has already solved this problem by creating a utility calledLauncher.
Launcher is a small utility for launching programs that require DDE from applications that provide only a command line by which to invoke external modules. You can also use Launcher to specify a working directory where the option to do so is not provided (for example, in a file-type association in the registry).
Perfect!
So instead of setting the registry key to use clarify.exe, we’ll set it to call launcher.exe.
Here’s what my registry setting looks like now:
Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\clarify] @="URL: Protocol handled by CustomURL" "URL Protocol"="" "CustomUrlApplication"="C:\\clarify\\11.5\\client\\ClarifyClient\\clarify.exe" "CustomUrlArguments"="\"%1\"" [HKEY_CLASSES_ROOT\clarify\DefaultIcon] @="C:\\clarify\\11.5\\client\\ClarifyClient\\clarify.exe" [HKEY_CLASSES_ROOT\clarify\shell] [HKEY_CLASSES_ROOT\clarify\shell\open] [HKEY_CLASSES_ROOT\clarify\shell\open\command] @="c:\\apps\\launcher\\launcher.exe Clarify %1"
Launcher.ini
Launcher can launch many different apps, and it uses an INI file to define everything.
I can give it the command to launch, set the working directory, and give it a DDE command to use to send data to an already running clarify instance.
Here’s what my launcher.ini file looks like:
[*] override=%AppData%\Launcher\launcher.ini [Clarify] command="C:\clarify\11.5\client\ClarifyClient\clarify.exe %1" directory="C:\clarify\11.5\client\ClarifyClient" ddeexec="handle_clarify_url,%1" application=ClarifyApp topic=Clarify ifexec=""
Notice that the ifexec command is set to blank. This means that if Clarify isn’t running, and launcher starts clarify, don’t send it a DDE command. We don’t need to, as the clarify URL will be passed as a command line parameter instead.
So, between the registry and launcher.ini, I now have exactly what I want.
Scenarios
If clarify.exe isn’t running, clarify.exe will get launched and the URL will get passed as a command line parameter, which gets handled by CB code inside the initialize_app subroutine.
If clarify.exe is running, a DDE execute call will be made and the URL will be passed in as part of this. Notice that in launcher.ini, the ddeexec entry is set to handle_clarify_url, which is the same subroutine name I used previously to handle a clarify URL passed in on the command line. Again, global CB code handles the DDE command.
Lets see this in action. As an example, I’ve simply included a custom URL in an email.
In Action – Clarify not running
A custom clarify:// URL launching the Clarify Client and opening an existing case
In Action – Clarify already running
A custom clarify:// URL using a currently running Clarify Client instance and opening an existing case
Pretty sweet!
Business Rule Emails
One additional snag I ran into is that business rule emails aren’t HTML. So, most email clients won’t recognize clarify:// as a URL. Which means that a clarify://case/12345 URL won’t be clickable in a plain text email.
But, email clients do recognize http:// as URLs, and they’re clickable – even in plain text emails. So, how can we make an http:// URL become a clarify:// URL? One way is to use an email shortening service such as http://tinyurl.com.
I created a tinyurl with a custom alias of clarifyapp. So, a URL of http://tinyurl.com/clarifyapp/case/12345 will be turned into a URL of clarify://case/12345
That works.
Note to self: Make Dovetail Rulemanager support sending HTML emails. (we’ve actually had this as an open enhancement request for a while now. Might be time to make this happen soon.)
Summary
In summary, here’s what I did to make all this work:
- Add some ClearBasic globals code for handling command line parameters and for handling clarify URLs.
- Add registry keys for handling the custom URL protocol
- Use launcher (and launcher.ini config file) to launch clarify, set its working directory, and send it a DDE command if its already running.
Nice to Have
Since the last two steps need to occur on client machines, it would be nice to create a simple installer that does all this stuff local to the client machine. A task for another day.
Final Summary
This whole thing originated form a customer I was working with recently. They asked if this was possible (having a URL in a business rule notification that would take you directly to the case that the notification was about). I had no idea if it was possible or not. Now I know for sure it can be done.
Rock on.
