I have pretty much standardized on SSO as a resource for getting parameters and values for Orchestrations.  I started doing this with the BizTalk Deployment Framework (BTDF).

Recently, I was at a client who chose not to use BTDF, but we still needed a way to store and retrieve values from SSO.

So here’s what we did.

  1. The first thing you probably want, is a free tool to update SSO.   Microsoft now provides this, as an MMC (Microsoft Management Console) Snap-in.Once installed, you have to remember the directory it’s stored in:

When you click on the “mmc” (the .msc file), it loads a snap-in in MMC, allowing you to maintain your SSO applications and variables.

2. Use the tool to add applications, and to add/modify key/value pairs in the app.



Below shows the pop-up menu when you right-clik on an application.



When you choose “Add Key Value Pair” you can enter the values as shown below:


Years ago, Richard Seroter laid the groundwork, and created an SSO C# Windows-Form utility that essentially does the same.

The code he provided still works with the MMC snap-in above.

3.  Access your variables (key/value pairs at run-time).

a) Create a C# helper utility to share across your applications

    // had to remove "Static" from class below to get it to appear in BizTalk Map 
    public class SSOConfigHelper
        private static string idenifierGUID = "ConfigProperties";


        /// Read method helps get configuration data

///The name of the affiliate application to represent the configuration container to access ///The property name to read /// /// The value of the property stored in the given affiliate application of this component. /// public static string Read(string appName, string propName) { try { SSOConfigStore ssoStore = new SSOConfigStore(); ConfigurationPropertyBag appMgmtBag = new ConfigurationPropertyBag(); ((ISSOConfigStore) ssoStore).GetConfigInfo(appName, idenifierGUID, SSOFlag.SSO_FLAG_RUNTIME, (IPropertyBag) appMgmtBag); object propertyValue = null; appMgmtBag.Read(propName, out propertyValue, 0); return (string)propertyValue; } catch (Exception e) { System.Diagnostics.Trace.WriteLine(e.Message); throw; } } }

b) Call that C# helper from your orchestrations

In the example below, strSSOAppName and strYNTraceOnFromSSO are first defined as orchestration variables (of type “string”):

strSSOAppName = "Demo";

strYNTraceOnFromSSO = MyLib.Common.BizTalk.Components.SSOConfigHelper.Read
                                              (strSSOAppName, "YNTraceOn");

strYNArchiveXML = MyLib.Common.BizTalk.Components.SSOConfigHelper.Read
                                              (strSSOAppName, "YNArchiveXML");

Then for example, later in the orchestration, I can have a “Decide” shape with a rule that tests:

strYNArchiveXML == "Y"

Based on the value of that flag, I can choose whether or not to send a message to an archive port.

Note for security: Your orchestration will need to run in a host instance that has been defined at least an “Application User” to App.  That can be set in the BizTalk Admin Utility that is installed when BizTalk is installed.  (See screen shot towards the end of this article.)

4. Deploy from Dev to QA/PROD

Export your SSO “app” from the Dev system. Right click on the app, and choose “Export Application”. The following screen will appear. You must give it an encryption key. If you don’t have any super secret variables in you SSO, then can set a standard of using your app name for the key name. Once exported, the file will have a .sso file suffix. You can open it with notepad, but it will be encrypted. To import into the target system, the person doing the import will have to know the key you assigned.

Comparison to BTDF’s SSO tool BTDF uses an Excel spreadsheet to enter all the variables and values. The advantage of BTDF is you can put in the values for each and every environment across the columns of that spreadsheet. Then, if I recall, BTDF stores an XML in SSO, and that SSO contains all the key-value pairs. So the tool above and the BTDF tool work differently, the the variables stored in one cannot really be viewed or updated by the other. BTDF also provides a C# windows form utility to update their SSO variables (sometimes needed, for example, in Production, to change some value on the fly).

By the way, when you change a value in SSO, it’s available “almost” immediately. Maybe it’s cached for a few seconds, but not for long.

Why is all the above needed when BizTalk installs with Administration and Client SSO utilities?

These are the two utilities included when you install BizTalk on a machine:

These utilities have never been that useful for me, except to change the SSO security for an app.

Here’s a trick you need to know. When you oepn the SSO Admin tool, you won’t see the applications above without clicking on the following obscure settings. You have to go to “Affiliate Applications”, right click then “View”, then check “Config Store”.


Then when you scroll down to the bottom, you will see the types of SSO applications created by the above utility (or BTDF). There will be a very long list of GUIDs in the “Name” column, then your apps will be at the bottom.


Now, you can right click on the ‘Affiliate Application” named “Demo” and select “Properties”. The following screen appears, and for the screen shot, I have already clicked on the “Fields” tab at the top.


You can see that the values in the “Label” column match the “keys” of our “Key/Value” pairs. So for whatever reason, Microsoft did NOT provide the ability to add or modify what are called “Labels” above. It seemed to take a few years later for them to create the MMC snap-in (described at the top of this blog).

Unless you are new to BizTalk, you maybe more familiar with the “Accounts” tab, shown below.


Only users defined as either an “Application Administrator” or an “Application User” can read/write values in the SSO application. Your BizTalk orchestration will be associated to a Host Instance (the process under which BizTalk runs).  That Host Instance runs under the security of a userid, defined in BizTalk Admin console. Typically, a user group is defined as the Application User, and the Host Instance userid is added to that group.

I hope this gives you an overview of how to use SSO with your BizTalk Orchestrations.  I used to put some of my variables in the BizTalk application configuration file (BTNTSVC.exe.config and BTNTSVC64.exe.config), but using SSO is much more “elegant.”  Those config files had several downsides:

  1. There are two files to update, and you have multiple servers in your group (for failover/high-availability), you have to update them, or copy them, to each server.
  2. You have to cycle the host instances for any change in the .config files to become effective.
  3. You don’t have to risk messing up a critical file. If these BizTalk .config files are edited improperly, then BizTalk might not come back up until the mistake is corrected.

Especially in production, it’s a lot easier to use the little GUI utility above to update SSO.

Tagged with:

Filed under: BizTalk