ClickOnce and the CX Launcher

Working on some yet to be released features for the CXDev Toolbox I have come across a lot of interesting details around the ClickOnce installer and the CX launcher. This article won’t be relevant to a large number of users, but for those few who are hacking around this is for you.

My goal was to allow users to download, install and launch the CX Console with a single button click. I’ve known for a while that you can launch the RightNow.CX.exe with some command line arguments, but it had always been for an installed site and one where I knew the crazy path to where ClickOnce had installed it. For example: C:\Users\{your user name}\AppData\Local\Apps\2.0\YL5XV20Q.BWX\G320NTL3.T5P\righ..obot_d163e684c1e033df_0012.0005_116769316769c8d6\RightNow.CX.exe. Not only is this impossible to determine but every site is different. So I started from a different point of view: the ClickOnce installer itself.

Magic URL #1
The ClickOnce installer, regardless of custom CNAMEs, is always available for a site at https://installer-{databaseName} which is super handy, but the database name for a site is only loosely tied to the site name itself and as far as I’m aware there’s no way determine it… except for this:

Magic URL #2
If you know the base URL for the site and the name of one of its interfaces (which can be found via ROQL: ‘SELECT Name FROM SiteInterface’) then there’s this XML file out there: https://{baseURL}/cgi-bin/{interfaceName}.cfg/php/admin/installer_settings.php. This file contains all sorts of interesting tidbits, most of which I’m unclear of it’s purpose, but here’s a sample (redacted):

<?xml version="1.0" encoding="utf-8"?>
<InterfaceSettings Language="en_US" Id="1" Name="{siteName}" Url="{interfaceRootUrl}" DbName="{databaseName}">
<MinWindowsVersion>NT 5.1.2600</MinWindowsVersion>

For this use case all I need is the name of the database, which is in the first element of the file as DbName. Now we can successfully create a URL for the launcher, but when you download it and run it you get this lovely error:

It installs just fine, but it won’t run. This error however is not coming from the ClickOnce process. It has closed, but before it did it fired off RightNow.CX.exe where it installed it to. However without the settings.xml file that lives in that same directory it doesn’t know what site its supposed to connect to. Unsurprisingly, finding documentation on the command line arguments available to the exe was.. Impossible. So here they are (don’t ask):

  • dbname - the name of the database to connect to
  • launch - a URL to the root of an interface, of the form: https://{baseURL}/cgi-bin/{interfaceName}.cfg
  • interfaceList - unknown, but my guess would be this is the list of other interfaces, probably just their names, that you can log in to
  • lang - unknown language of the site? Maybe just the language of the launcher. Format is probably either the ID of the language (ex: 1) or a shortname (ex: en-us)
  • uname - username to log in with
  • pword - password for the user
  • auto - when used along with uname and pword this will automatically log the user into the console without prompting them for any information, without this set the uname and pword values appear to not do anything. Options are ‘true’ or ‘false’
  • trace - unknown but seems to produce additional information in the log. Options are ‘true’ or ‘false’.
  • enc_token_ref_id - unknown but I believe it’s an encrypted SSO token
  • login - again unknown but my guess is that it’s the username for the SSO token, how this differs from uname, I’m not sure
  • proxyusername - unknown
  • proxypassword - unknown
  • UseInternalIdP - unknown, but based on the name I’d imagine it’s related to SAML where CX is the identity provider

As you can see there’s far more unknown than known. If you have any insight into these options please leave them in the comments and I’ll update the document. These arguments can be passed to the application as ‘RightNow.CX.exe key=value...‘

The first two options are the ones specified by the error message so clearly they need to be provided, but how… When you download the clickonce manifest it comes across as a .application file, and while you can “run” it there doesn’t seem to be any way to specify run time arguments. However, if you launch it via URL, through Internet Explorer (and probably Edge) then the arguments get passed all the way through to the RightNow.CX.exe when the launcher process finishes. So our final URL for installing and launching the site looks like:

https://installer-{DBName.Replace('_', '-')}{InterfaceUrl}&dbname={DBName}

If you use this as an argument for IExplore.exe it will pop up IE, download the installer, launch it and pop the console login. If you know the username and password for the user you can specify these options as well using uname and pword arguments (also set auto=true). Now the user will automatically be logged in.

Hopefully this information will be helpful to others trying to automate the login process. Please share whatever you learn in the comments below.

Categories : 

Zircon - This is a contributing Drupal Theme
Design by WeebPal.