Sunday, 10 May 2020

TechNet Gallery to GitHub Migration Tool


As you may or may not be aware Microsoft are making a move to close down the TechNet Gallery web site. This website is the location where I had previously posted all of my tools over the past few years and is also jam packed full of other great community tools as well. In the first stage of the shutdown, Microsoft has put the TechNet Gallery pages into a Read-Only mode where you can still edit existing posts but cannot create new posts. This first step is to give people time to download their posts and move them to another location before the final shutdown of the site.

I find this news to be quite concerning because I know that I still find useful resources on TechNet Gallery all the time. So I've decided to try and do something to help people move their content off TechNet gallery to a safe harbor before it's too late. To do this, I decided to put together a PowerShell tool that will both download content from TechNet Gallery and prepare it for upload directly onto GitHub. This post also describes the steps to uploading the files onto GitHub to make the process as easy as possible.

How does the tool work? Well, you feed it one or many TechNet Gallery URL(s) and it will download the posted file and all the text and images from the site into a folder for you. In addition to this, it will convert all of the text into a Markdown based README.MD file (and refactoring image URLs to move to GitHub) so it can be directly uploaded to GitHub to display the exact text that you had on your TechNet Gallery post (minus any code snippets). All you need to do after this is follow a simple process of creating a new GitHub repository and upload these files to it. You will then end up with your TechNet Gallery content re-hosted in a very similar format on GitHub.


The Differences Between TechNet Gallery and GitHub


TechNet Gallery was designed to be a relatively simple CMS style system that allowed you to upload a file (of any type) and put some blog post style text and images with the file to explain whatever you wanted about the file. This concept is fairly easy to understand and didn’t offer too many bells and whistles. GitHub on the other hand was designed to be a source code repository with versioning features and functionality built in. As a result, GitHub has a much bigger capability set and complexity level than TechNet Gallery.

What does that mean when moving files and content over from TechNet Gallery to GitHub? It means that you have more options for how you can post and manage your files. For example, you could simply use it as a location to put your files or you could potentially start using the Git application workflow to manage the versioning of your files. Using these more complex components of GitHub is out of scope for this blog post. You could quite easily “git init” the folder that the tool creates and then link this up to a remote GitHub repository as a way to upload the content. I will assume if you know how to use Git then you’ll be more than capable of doing this yourself, and if not, then you don't have to use these features or you can read up on them as you see fit.


Backup / Migration Procedure


For the purposes of this blog post I am going to make this the simplest procedure possible which does not require that you install and use Git. Instead the process will use the GitHub web interface to upload your files for storage on GitHub in a similar way to how you would have used TechNet Gallery.

Firstly you need to go and get the URL of your TechNet post. This will look something like this one for one of my posts:

https://gallery.technet.microsoft.com/Teams-Direct-Routing-Tool-42c0bdef

Once you have this you will need to sign up for a GitHub account. This is free and offers you a heap of functionality without asking you any of your hard earned dollars (thank you Microsoft!). I’m not going to show you how you do this because it’s pretty straight forward. When you sign up you will be asked to create a GitHub account name. You will require this account name if you are migrating your images over to GitHub using the tool.


Head over to my GitHub repository and grab of a copy of the script I wrote for downloading the files and generating a README.md file for use on GitHub. Click the link below to go to the repository:




DOWNLOAD SCRIPT HERE


When you run the tool you can either use PowerShell flags to input your information into the tool or not use any flags and the script will ask you to input the information that's required. The flags that the tool uses are as follows:

-MoveImagesToGitHub (Default TRUE) - When set to $false you can retain the original location of the images from the TechNet post in the GitHub readme.md file. If these originally pointed to an external location then you can keep them there but if you uploaded them to TechNet Gallery you will want to move them as they will disappear when the site is taken down.

-TechNetURLs - This flag is where you can input a comma separated list of all the TechNet URLs that you want to download. If you don't use this flag the tool will ask you for a URL when it runs.

-GitHubAccount -  This flag is used for updating image URLs with the GitHub account location where it's going to be stored. This will be the account name that you sign into GitHub with. If you don't use this flag and the script determines that it's required it will ask you for it.

-GitHubRepo (Default TechNet Post Title) - This is the Repo name that the files will be uploaded to. If you don't enter this then the TechNet title will be used. If you have a specific name you want to use then use this flag to set it.

To run the script with flags you will use the following format:
.\TechNet-Gallery-to-GitHub-Migrator.ps1 -TechNetURLs "https://gallery.technet.microsoft.com/Teams-Direct-Routing-Tool-42c0bdef", "https://gallery.technet.microsoft.com/Lync-Skype-for-Businesss-d422212f" -GitHubAccount "<your account name>"

After you have run the script it will generate a new folder for each TechNet Gallery post in the root folder that you ran the script from. These folders will be named using the title of your TechNet post with dashes replacing spaces. This is a common naming convention for GitHub repositories (not the only way, but a common one). The script is designed based on the assumption that the repository that you create in GitHub will have this same name (and same format).



Sign into GitHub with your account. Within GitHub go to your Repositories page. In here you will see a green button marked “New”. Click this button to create a new repository:



To name the repository, copy and paste the name of the folder that the tool created (this is the same as the TechNet Gallery post title). I recommend you use this same name for your GitHub repository when you create it (unless of course you wrote weird or super verbose things in your title to try and up your SEO). Below I have copied the name of the folder:



The New Repository page on GitHub asks for the following information:



Fill in the repository name and description with the folder name that the tool created. Select “Public” repository type if you want others to be able to see it on the Internet. Once you have done this click the “Create repository” button.

You will now be taken to a page that tells you how you can connect to this repository using Git methods. However, we are just going to use an entirely web based creation process for simplicity. Click the “Uploading an existing file” link as highlighted below:



You will now be taken to a page for uploading your files. Drag and drop all the files from the folder (the script created) on the web browser window in the location shown below:



You should now see a list of your files in the page as seen below. Click the “Commit changes” button to upload the files:




You will see your newly created repository with all your files in it. The contents of the README.md file will be displayed in all its glory below this as GitHub uses this as your repository’s information text by default. It should also render all the Markdown in the file nicely with headings, bolding, dot point and images being displayed. This should make the page look similar to what you would have seen on the TechNet Gallery page for your content!





 Tweaking or Changing the README.md Text


Minor tweaking may be required on the Readme.md document to perfect the layout. The good news is you can do any corrections you need to do in the GitHub web editor. Simply click on the README.md file and then click the Edit button. This will take you to a text based editor in the web page where you can make your changes. In this example the Protocol Documentation heading is not quite rendering properly as being bold because there is a return carriage between the second set of asterisks. So I just need to simply move them up to the line that they heading is on and click the Commit Changes button at the bottom of the page.

Note: Code snippets in the TechNet Gallery text will not be carried over to the README.md file (lots of people include their entire scripts in the body text which doesn't translate well to markdown). If you have put smaller lines of code examples in your text you will have to add them manually to the README.md file.




And you’re done!


What Next?


The good news is that you have a publicly available backup of your TechNet Gallery content. It's up to you on how you would like to administer this moving forward on GitHub. As I mentioned earlier, you may choose to start using the Git workflow and downloading and managing your repo(s) with Git commands (commit, push, etc). You may also choose to use the Releases page in your repo to generate tagged and versioned releases. It will depend on the type of project that you are migrating as to how you may choose to do this. For a project that is not getting changed much you may just choose to put up and leave it. However, for a project that you are actively doing a lot of updates on you may choose to start using Git. There are many resources on the web that will explain Git and how it works. Git will be a lot to digest when you first start using it and it's something that you really need to start using in practice to get your head around. As they say; there's no better time to start something than right now, so hop to it!


The Wrap Up


I have migrated 14 of my tools that were up on TechNet Gallery using this process so the process has been trialed and worked successfully for me. As I mentioned earlier in the post; TechNet Gallery has loads of great content on it which I really hope does not disappear into the abyss when the site is closed down because people put the migration in the too hard basket. I really hope that this tool and blog post do something to make the process a bit simpler and give you a framework by which to migrate your tools as well. If you have any issues with the script, let me know.


Read more →

Tuesday, 21 January 2020

Portals for Office 365

Office 365 is amazing: it has tonnes of great applications and tools for getting your work done. However, it can be quite overwhelming at times, getting access to all the applications and administrative portals it offers. It can be especially hard when you have multiple accounts and/or different tenants, whether that be full accounts or guest account access in Microsoft Teams. I wanted to make this easier, so over many months I developed an application that was designed to give you a simple workflow for accessing the various administrative and user tools within Office 365. This application I call Portals.



Releases:

For more information on releases, check out the change log over at GitHub: https://github.com/jamescussen/PortalsReleases

Known issues:

The app has the following known issues:
  • Screen sharing does not work within meetings (although sharing of PowerPoint presentations does). This is due to an issue with Electron using a closed display capture methodology. Currently there doesn't seem to be the impetus for them to change this at this stage (https://github.com/electron/electron/issues/16513).
  • When in edit mode and moving accounts up and down, the open or closed state of the accordion item for the account will not move with the account. The open or closed state of the items prior the move will be retained after the item has been moved. This is weird but usable 😊
  • Portals currently references the normal Enterprise Office 365 portal URLs to connect to services. This means it will not be able to connect to any different URLs that may be used by the other specialised Office 365 cloud variants (eg. 21Vianet, DOD or GCC versions).
  • In Power BI if you try to update a dataset's authentication with OAuth the Power BI site will launch a new window and do a redirection which fails. The window will open and then disappear without you being able to authenticate.
  • Exchange ECP has some pop up dialog windows such as the user selection pop up in the Shared Mailbox configuration section that uses a method of passing information between windows that doesn't work with Portals. This currently is a limitation. 

If you have specific feedback about the app you can send it to myteamslab(at)gmail.com



(Simply download and install the "PortalsInstall-win32-x64.exe" installer file from the GitHub releases page. All future updates should automatically get pushed to you without you needing to manually download them)


Portals Walkthrough Video


Rather than write many thousands of words that you may not have the time or energy to read, I opted to make a walk-through video of the application. This should give you a quick and hopefully painless overview of the main capabilities of the app.



Adding Accounts


When you add an account, you can add either a regular account which has access to all the applications within Office 365 (this might depend on the account licence level, e.g. E1, E3, or E5 licenced account for example) or a Teams Guest account. The purpose of the Teams Guest account type is to allow you to create a separate account session that can log into a Guest Account tenant in a separate window from your home account. This allows you to have both Guest Accounts and your regular account Teams sites open at the same time (woot!).



Tenant Name for Regular Accounts:
To add an account click the Add Account button:



You will then be presented with the Add Account Dialog. You enter the Email Address of the user for which you want to add an account:



After this, you have a fill in the Tenant Name. When you’re adding a regular account, the Tenant Name is used within SharePoint and OneDrive URLs. The easiest way to find out what the Tenant Name needs to be is to log into the www.office.com website in a browser and then click on the SharePoint item:



This will open the SharePoint home page for your tenant, which will have the tenant name at the beginning of the URL -  as shown below:


  
When you click on the SharePoint portal, the URL will use the tenant name you enter in Portals as shown below:



Below is an example of the format of the working OneDrive URL:



If you get the tenant name wrong, then the SharePoint and OneDrive Portals will not load properly.

Tenant Name for Teams Guest Accounts (when you’ve ticked the Guest Account checkbox):
When adding a Guest account, the Tenant Name should be the name of the organization for which you are a Guest. In this example, John Woods is a guest account for a partner organization called “mylynclab”.



This name does not matter as much as the regular account tenant name, as it’s not used in any of the URLs. Instead, it gets added as a designator in brackets next to the account name to signify to you which tenant the guest account is accessing. This is an example of what the account looks like once added (in this case mylynclab is the tenant for which John Woods is a guest):




Password Security


Portals does not save any of your Office 365 passwords. It behaves in the same way as a browser does, when you sign into Office 365 using Portals the application is given a temporary access token by Office 365. This token and all other cookies presented to Portals are encrypted with AES 256 encryption and a long random password when they're written to disk. So your passwords are never saved and any temporary access tokens are fully encrypted.  

It's recommended when you sign into Office 365 in the Portals that you select to stay signed in. This way you don't have to keep putting in your password. Example:



Edit Mode


In edit mode you are able to edit the layout and setup of the Launcher window. When you click the edit button you will see all the portal icons start to wiggle. This lets you know that you can move them around. Crosses will also appear on the right hand side of portal buttons so you can delete them. There will also be a few extra buttons that appear at the bottom of each account section, which allow you to add portals, edit the account preferences for each account, and delete accounts. Finally you will also see an up and down arrow next to each account appear which allows your to reorder the accounts up and down in the accordion view. Using these tools, you should be able to craft a layout that suits your specific needs.



Toast Notifications


When using Microsoft Teams it's important the when people are trying to call or message you that you are aware of it. This is especially the case when you are logged into various Teams accounts at the same time.  As a result, I have designed the app to have a Toast based notification system that will pop toasts when you receive an inbound call, direct message, or team based notification. When you click on the toast the app will bring the window that the notification came from to the front so you can quickly and easily answer the call or respond to the notification.

Below is an example of a Calling toast (in this case Bob Kelly is getting called by a John Woods):



Below is an example of a Notification message (in this case Bob is getting a message from John Woods):


Each account has been given its own settings for turning off notifications for calling and messaging within Portals. These can be accessed by clicking the preferences button under an account when in edit mode. The two checkboxes can be seen below:


If you would like to have more granular control over which message notifications will pop toast windows you can go into the Teams app settings (Click on your user profile in the top right of Teams > Select Settings > Notifications). In here you have full control over the type of notifications that you will receive a toast message for (just like in the Teams app).


An example of this is that if you have "Banner and feed" set for "Like and reactions" then you will receive a toast like this one:


If you were to set "likes and reactions" notifications to "Off" then you wouldn't get any toasts when people react to your posts. This gives very fine control over how many toasts you will receive in Portals.

Donations


I have not previously accepted any donations for any scripts or apps that I’ve released. However, in this case I spent a huge amount of time working on this application and I feel that I’ve built something that will help with some major pain points that many people have with Office 365. As a result, I added a Paypal Donate button into the Preferences dialog which you can use to make a donation representative of the value you feel you get from it. I have also built the application to support automatic updates and I would like to continue to develop and improve the app where possible, so donations will certainly help to keep encouraging me to put further time into it. If you choose to donate, then I thank you very much. Paypal.me link: https://paypal.me/myteamslab

The Wrap Up


It’s safe to say that this is the largest and most complex application I have made and released to the public. It’s essentially a completely customized web browser, built for a specific purpose and workflow of my design. When I started the project many many months ago I hadn’t developed anything in Electron or even written anything serious in Javascript before. As you might imagine the learning curve has been large but I’m happy with the way the application has turned out so far and have high hopes for its future. Thanks for reading and downloading, enjoy!


Read more →

Popular Posts