Migrating FSLogix Profile Containers to Citrix UPM Containers (and other new features in UPM 2308!)

Apologies if I seem to be going a bit bonkers with the UPM Containers blogs recently, but I’ve been doing a deployment of them and if you follow the mantra of “write what you do”, then I really seem to have no other choice but to put them out there 🙂

Citrix UPM Containers are now, in my opinion, better than FSLogix Containers (whether that be full-fat Profile Container or a mix of Profile/Office Container or even Office Container on its own), because they have more features, more granularity and are actually actively under development – unlike FSLogix seems to be. Rumour is it that Microsoft’s next move with FSLogix will be to rename them, rather than add any useful new features. But hey-ho.

So if you’re already an FSLogix Profile Container consumer and you want to switch to or test Citrix’s UPM Container solution, what options do you have? Creating new profiles would be a bit of a problem, so it’s always better if you can migrate existing ones across, at least to some degree.

Architecturally there aren’t a lot of differences between FSLogix and UPM container implementations but there are enough to make it a bit of a hassle to do manually. Some of the folder names and structures are different, which is the main issue.

Preparation

Now when migrating profiles. it’s generally always a choice between “migrate at user logoff” or “migrate ahead of time”. Because the migration between FSLogix and UPM requires some admin-level access, this means that “migrate ahead of time” is probably the best choice (although I will see if I can do a “migrate at user logoff” somehow when I get the chance to do some testing).

The easiest way to drive this is to create an Active Directory security group with all of your target users in it and use this to migrate them at a point in time. You can either do it before you switch them or just prior to the actual changeover.

If you have different OS versions of profiles to migrate, separate them into different groups. The UPM migration tool can only do one profile version at a time.

Also, it goes without saying but you will need to download Profile Management version 2308 as this contains the migration tool. You don’t specifically need to upgrade your target devices to UPM version 2308 or VDA 2308 (although it would make sense)….because…

New 2308 features for Citrix UPM

…there are all these cool new features now added, further bringing UPM ahead of FSLogix.

• Default capacity (size) for UPM containers

• Automatic expansion thresholds and limits for UPM containers

• UWP app roaming for UPM containers (YES!!!!!!)

• Turn off the default (concurrent) access for UPM containers and use them in exclusive mode

Awesome – another great bunch of features in the latest release.

Meanwhile – back to migration. As I said, you don’t need the 2308 UPM agent to do the migration – but given that you’ll need to download it anyway (and there is a painful bug in 2305 that can stop containers working as well), why would you not install the latest version for your migrated users?

Performing the migration

Now, inside the UPM 2308 source files you will find a folder called “Tool”. Within here resides a PowerShell script called CPM_ProfileContainer_Migration_Tool.ps1

Obviously your users already have to have FSLogix profile containers existing somewhere for this to work 🙂

You also need to make sure you have an SMB share configured to hold your UPM Containers with the appropriate filesystem permissions (see my earlier blog for the minimum required permissions).

Now, this bit is very important – currently the UPM Container migration tool is in its first iteration, so improvements will be made over time. One of the current limitations is that it only works on Profile Containers with the default naming format (so that means SID_username for the container folder, and Profile_username for the VHDX within). If you have used the policies for “Flip-flop directory name”, “SID Directory Name Pattern/Match” or “VHD Name Pattern/Match” then the migration tool will be unable to work for you. Currently (and I say currently as Citrix are going to update the tool to fix these limitations) if you wanted to migrate profiles with these policies applied you’d need to rename the folders/files back to the defaults first.

If your profiles match the required format, you can start migrating by running PowerShell ISE (or other PowerShell tool) as admin and start the script. You will see the following screen:-

Choose the correct option – obviously option 3 will be the most common although some of you will use option 4 if you have used VHD format instead of VHDX.

Also note that you can migrate Citrix UPM file-based profiles or even local profiles to UPM containers (although bear in mind that if local profiles exist on a device with UPM Container enabled they will get migrated automatically anyway). Perhaps the Citrix policy setting that does automatic profile migration will be updated in future to trigger this script directly, maybe?

Once you’ve entered the selection it will ask you which users or groups you wish to migrate, hence why adding the target users to an AD security group is a good idea. You need to enter them in the format DOMAIN\GROUP or DOMAIN\USER. At this point the tool will tell you how many users will be migrated and where to find the log file also. Be careful not to make an error in the group name as even if the group does not exist it will not re-prompt, it will move on to the next stage and you will need to break the script execution.

Now enter the path to the FSLogix profiles (the root folder)

Next you need to enter the full store path to the VHD or VHDX location you wish to migrate the FSLogix profiles into for UPM. If you are using %USERNAME% or #SAMAccountName# in the UPM store path then be aware that you can only use %USERNAME% in the script input, not the AD attribute (although it will work just the same). Also, be very aware that the %USERNAME% variable is case-sensitive so you MUST enter it in uppercase.

You next need to select the OS version of the profiles you are migrating. There is a list provided to guide you in the tool and also a link for further reference.

The profile migration tool will then attempt to run, you will see a progress bar for each user

A summary will be displayed. If it is successful it will be green

And you can see the new profile created for the user in your UPM store

If it is unsuccessful (example shown below) it will be red

And will tell you where to find the log of the errors. I’ve shown the log errors below from this example.

As you can probably guess, this was caused by using custom directory name patterns, so it should be easy for you to tell why any failures have occurred.

Once you have the new container created, you simply need to remove FSLogix from your target devices (or disable the Profile Container functionality if you need FSLogix for other features) and then install the UPM agent with the required settings. As you will already have profiles in your user store, your users will be able to log on and get their existing settings – just they will now be on UPM Container rather than FSLogix.

Summary

This is another great piece of tooling from Citrix to make it easier to migrate from FSLogix to the UPM Container solution (or, to be fair, from UPM file-based also). It’s very much a first iteration and it is a bit annoying that it does not work on custom directory/file names at the moment, as most implementations I have done use these settings, but a bit of scripting could do some quick renames ahead of time. I’m not going to bother writing that myself, though, because I think Citrix will give us the functionality pretty quickly.

What I might have a crack at though is getting this script to run elevated so you can use it at logoff to do automatic migration – let’s see if we can do that in the next couple of weeks.

Also, let’s not forget about the new features we have also got in 2308 (along with bug fixes for local caching and a really annoying issue in 2305 where containers just didn’t work properly). Exclusive container access, default container sizes, controls for expansion and (a big one) proper UWP access (this is something I need to test!) – Citrix continues adding features at a great rate.