External Application inside Sitecore Desktop

Recently I had to integrate Sitecore with an external application written in PHP. The integration included making the PHP application appear inside the Sitecore desktop, so it would appear to the end user that the external application was actually a part of Sitecore. Now, this is actually quite easy to do as we can make any ASPX page an application inside the Sitecore desktop.

An application definition is kind of like a normal navigable item on your website. You have to define the presentation of the application before you can run it.

Applications are defined in the core database, so once inside the desktop, use the database switcher in the bottom right of your screen to swap to the core database.

Now we have to create a layout for the application to give us an ASPX to create our presentation. All we'll do in our ASPX is Response.Redirect to the application we want to integrate. We can redirect comfortably because each window in the desktop is actually run inside it's own iframe, so the host environment won't upset the application and vice versa.

Open the developer centre and create a new layout. Next open the content editor and navigate to /sitecore/content/Applications. Now create a new "Application" item and define it's presentation as just using the layout we created.

Now to add a shortcut for the application into the menu so we don't have to use the "Run" application to execute it. These are defined at /sitecore/content/Documents and settings/All users/Start menu. I want it to just appear in the "All Applications" section, so I'll navigate down to the "Programs" item in the content editor and create a new "Application Shortcut" there. We just have to fill in the "Application" field on the shortcut item to point at the application we created above. The application won't appear immediately in your menu as you have to refresh the client to have the menu recreated. The easiest way to do this is to switch back to the master database using the database switcher.

If you don't see your shortcut on the menu after you've switched back to master, check Chris Wojciech's blog post Create application links in the sitecore startmenu (don’t work). For some reason the insert link dialog appends a ".aspx" after your applications path. Just remove the ".aspx" in this field and all should be fine.

Now to have my application redirect. You could either do this in code behind, or even inline in the aspx file. I'll choose the latter option here for brevity. My layout's aspx file should look like the following.

<%@ Page language="c#" Codepage="65001" %>
<%@ OutputCache Location="None" VaryByParam="none" %>
<% Response.Redirect("http://www.google.com"); %>

We should probably ensure the page's URL is configurable incase the URL of our external application changes. This could be placed in a config file, but I prefer the content tree. Seeing as though this config data is to do with a Sitecore client application, I'll store it in the core database. That's also where I have to create my template which defines the structure of the config item.

To read the config item and redirect to the configured URL, I just change the last line of my aspx file. Note that when inside the desktop the Context.Database is by default the core database.

<% Sitecore.Data.Items.Item config = Sitecore.Context.Database.GetItem(
  "/sitecore/system/Modules/External Application/Config");
Response.Redirect(((Sitecore.Data.Fields.LinkField)config.Fields["url"]).Url); %>

Now I can point the URL field at any external (or internal) URL and have the application appear inside the desktop and appear as if it's part of Sitecore. That might be fine for basic applications, but what about those that require a login? You don't want to have your users logging into Sitecore and then having to type login information into another window. Luckily through the magic of HTML we can post a populated form to whatever URL we desire. For this example, I'll alter the above application to silently log into an application written in PHP, that has a standard login form. (I chose PHP cause PHP reads the raw form data and doesn't augment it with control classes like .net does. Just makes my example easier.) The username and password for the account being used are stored in the config item along side the URL which we'll post our form to. This saves the users from having to enter an additional password and allows single sign on. This also only works if the same account is being used by everyone for the external application, unless you changed the configuration item to be per user.

So now my ASPX file looks like the following:

<%@ Page language="c#" Codepage="65001" %>
<%@ OutputCache Location="None" VaryByParam="none" %>
<%@ Import Namespace="Sitecore" %>
<% Sitecore.Data.Items.Item config =
  Sitecore.Context.Database.GetItem(
    "/sitecore/system/Modules/External Application/Config"); %>
<html>
  <body onload="javascript:document.forms[0].submit();">
    <form action="<%= ((Sitecore.Data.Fields.LinkField)
config.Fields["url"]).Url %>"
      method="post">
      <input type="hidden" name="username"
        value="<%= config["username"] %>"/>
      <input type="hidden" name="password"
        value="<%= config["password"] %>"/>
    </form>
  </body>
</html>

What we need to populate into the form will depend on the target application. For example, when posting to a .net application it is not normally adequate to just fill in the form fields and submit the form. The dev normally hooks into the asp:Button's OnClick event and so you have to simulate the click event firing from the button control.

And another thing, don't forget the security. As the application definition and menu shortcut are just items, we can apply security to the items so only authorised users can execute the application or see it on their menu.