Sometimes a break is what you need...

Its been a few months now since I said I was close to releasing the toolkit to general public.  You may now commence producing the 100 lashings I deserve.

I'll wait.

No really.

Go -- I'll be right here waiting for you to get back to punish me.

Well for those of you who decided to stick around I have a few pieces of news regarding the toolkit - a few excuses and a few things that sound like excuses but really are not.

First thing first.  

Toolkit has moved onto the 3.4 version mark from 3.3.  A few optimizations have found there way in as well as a new outlookless email system through SMTP (and part of the reason for the delay) as well as a few new ways on how various items (external applications) were handled and streamlined more.  As part of this process I learned some new powershell techniques, was humbled by Don Jones through his books/web instruction on the correct design functions for powershell functions and learned a few lessons from Jon Acuff (release stuff that is good, not perfect - you will never release an item if you strive for perfection).

So that being said here is my commitment to the internet and to anyone who wants this tool released to them.

In its current version the toolkit will be uploaded to this site on Saturday 4/27/2013 sometime.  As part of this, I will HAVE to write some information on how to setup the toolkit in your environment - its fully configured as is now for my jobs environment and I have had the luxury of almost a year of use to fine tune everything - and an intimate knowledge of the logic behind the code as well.

You will not be so lucky at first.

You will be struggling to figure out how the inner logic of my brain works - hence why I need to write some documentation for you. That is why I am waiting until Saturday for you to get your hands on it.

What will happen after the saturday release?

  1. Documentation updated on a frequent and regular basis
  2. More and more and more and more and more of the code will be commented
  3. Code cleanup (yeah.....) this is needed as I review my old code and see stupid things I did that should be cleaned up
  4. Potentially some functions will move away from quest and to the native microsoft ad cmdlts (hey - I love quest - they are a lot easier in some things than microsoft and a lot more troublesome in others)
  5. Full compiled exes of the application will be available - most of the application will allow you to overwrite the functions so this will not be an issue provided you have an idea/know what you want to do with that section of code - and each time I update the code for work (in the main EXE) I will release an update to the website.
  6. Examples of how to customize the toolkit released here on a somewhat frequent basis to show how it can be extended easily (and really - it is really easy to extend it - I made it easy for you to extend and I will not even use that extension ability half of the time)
  7. A new support site just for the toolkit through - I'm serious about this toolkit
  8. I'll answer questions as fast as I can - although I provide no warranty on the toolkit and what it will/can do to your environment - that is your responsibility to test it out before moving into production (I can make this promise: I will not go all Bobby Tables on you on purpose at least)

So that is my commitment.  Saturday is close at hand.  

Caffeine come to me!

Toolkit | Get-Architecture | Select Part 2

Its been a little while since I was last able to update anything on the toolkit.  The holidays (and some other things) got all mixed up at once preventing me from doing what I wanted to do.  Because of these delays, I am a little behind in my plans to release the toolkit "out in the wild".

But not all is bad news.

Due to this delay, this has given me the chance to think about how to execute a feature that has been requested by someone in my company as well as someone who I used to work with.  Combining powershell's ability to dot execute along with the flexible config file architecture of Toolkit 3 allows for (with just a few lines of code in the toolkit) the ability for customized data to be placed on the Toolkit's screen. 

Since this is a relatively new feature and I'm still vetting it fully - I won't go into explaining how everything works quite yet with it - but once it's done I'll be sure to explain that information.

With that in mind I will now continue with the overview of the architecture of the toolkit.


If you understand scoping in powershell you will have no issues with the toolkit.  

Except for locally defined/used variables - almost all variables in the toolkit are defined at the scope level.  This allows you to easily grab and use the same variables that the core functions of the toolkit use in your external files which extend the application.  For the most part, this means you will not need to try to figure out a way to "hook" into the application to get the data to either display of manipulate, just call the variable and you have full access to it the same as the core toolkit would. 

[Architecture]::Function Overrides

One of the newer features of the toolkit is that it allows you to override almost all of the native functions built into the application.  Currently this is established in about 30% of all functions/events and as time permits the rest of the functions/events will be updated to allow for them to be overridden.  Every time the toolkit enters a function/event it checks to see if the corresponding override file exists.  If the override file exists, then the code in this override file is run instead of the native function.  This has multiple advantages - one being that if a native function does not do something you need it to do, you can take the native function and alter it to perform the tasks you need (and thanks to all the core variables being of the $script scope you can access all the core data) the function to do as well as manipulate the forms as needed.  This also allows you to tailor the application to your specific needs without having to re-deploy the application (if installed locally) or compile the PS1 files into EXE.

To be able to document what functions call what files  I am currently working on a wiki page listing all the native functions as well as the override files the application looks for.  The code for each function will be provided so you can use as much or as little of each function as needed.

While I originally intended (and still at some point may do so) include a utility for you to be able to pull up the latest code directly from the toolkit, I have found that devoting time to keeping the data up to date on a wiki may be the most beneficial way to keep this information update.

[Architecture]::Custom external EXE files with parameters

Perhaps the newest feature of the toolkit which made its way into production recently was the ability to add application buttons on the main screen of the toolkit to launch external applications and provide a method for passing parameters to these external applications.  This grants the toolkit some new power, as before the only way to extend it was using EXE files which were launched from the custom applications section - which passed no parameters to the launching application - or through hooking into the various custom hooks to add new features.  There was no way to launch one of the custom EXE files AND pass data to it.  To accommodate this the toolkit was recently expanded so that if various items in the main configuration file were filled in (see wiki for information once the wiki is online) up to three buttons would be displayed on the users tab screen with the ability to launch the exe and pass to the exe data through customized parameters established in the configuration file.  I'm currently looking to see if it is feasible to add this function (optional) to all of the externally launched applications - but for now three dedicated buttons/hooks have been created to accommodate this.

As things slowly start to return to normal, I plan on putting in a little more time/effort to get the toolkit released.  The next blog post I post on this will be related to the initial setup/configuration of the application to get it running with most (not all) of the options configured.  As soon as this is done and the core features documented in the wiki I will be ready to release the EXE and the source files for the toolkit to the general public.

Until next time.

Toolkit | Get-Architecture | Select Part I

You can’t will a problem away, but you can architect it away.
— Coworker

As Toolkit 3 finished being prepared for general availability, it became apparent that the application needed a little more flexibility to allow it be customized without having to be re-compiled into a new exe.  In fact, the EXE which will be released can be taken, and with a few minor adjustments to external files,  operate completely differently than the stock exe file released.  To better understand this feature, lets take a look at some of the background architecture of the application.

[Architecture]::Configuration Files

Toolkit 2 did what it did well, but its limitations were eventually brought to light when it was requested that it be ported over to another domain.  All of the variables in Toolkit 2 were hard coded - domain controllers, email servers, path to external files, etc.  This was acceptable for use small scale and with simple code, but as things became more complex it became a hassle to maintain all of the variables.  For example, when the company transitioned from server 2003 domain controllers to 2008 domain controllers, all of the functions which used one of the old domain controllers had to be updated otherwise they would not function correctly.

To get around this, it was decided from the very start that Toolkit 3 would not have any hard coded variables, and instead everything would be stored in a configuration file.  (And this is 99% true - there are one or two items which are very specific for my current employer which are hard coded - but these items are clearly marked and easy to bypass.)

Due to the fact that various configuration files are used, Toolkit 3 needed to either be able to replicate the configuration files quickly or rely on a central repository of configuration files.  To accommodate this, the application was designed to reside on a network share and in essence stream over the network from the network share to the clients using the application - the program does not need to be installed on any machines.  This allows for the utility to use one central set of configuration files to prevent issues with replication delays, as well as files not making it to their ultimate destination and allowing for the files to be updated at any given time by an application administrator.  There are two main configuration files which need to be setup in order for the application to work correctly:

  1. path_info.txt::path_info.txt is a required configuration file which needs to be in the same directory of the executing Toolkit EXE file.  This file is a single line with the full path to the otk_config.otd file, the second mandatory configuration file.  This allows for the exe to be placed in a different directory from the rest of the configuration files, or be placed on a local pc instead of streamed over the network.  While the recommend mode of operation is to launch the application off of a shared network share, local copies of the application are supported for launching - but be warned that there is currently no function to auto-update a locally launched application.
  2. otk_config.otd::otk_config.otd is the second configuration file which is required.  This file contains the bulk of the Toolkit's configuration data, and while it contains a lot of the data, it does in fact point to other configuration files which may reside in any other location.   More data about the configuration/setup of the otk_config.otd file will be coming out soon along with an explanation of each of the settings.

Any other configuration file outside of these two, while helpful, are not required for the application to perform its basic functions.  Best practice is to have all of the configuration files in the same directory with the special files(additional utilities, override functions, email templates, and manual) in their own folder to better keep them grouped together.

[Architecture]::Dot Executing

A function of Powershell that is not utilized frequently, and I personally just learned about within the past year is what I call dot executing.  I'm not sure on what the official name of this ability is, but basically it allows you to call external script files and execute them within the same runspace as  your currently executing script/application.  The benefit of this is that you get access to all of the variables and other items (winform controls included) in the current runspace without having to do any tricky modifications.  For example, Toolkit 3 has multiple hooks for external files utilizing this method (including a new ability to allow you to override any of the built in functions without having to re-compile the code - more on this later) allowing complete customization of the application.  One such hook runs before any account is enabled.  The Toolkit checks for the existence of a file (as defined in the configuration file otk_config.otd) and if it is found, the file is executed.  An example of this is:


The most important part of this command is the beginning - .{.

The .{. tells powershell to execute the item after the second period in the same runspace as the currently executing script.  So for this example, the above variable $script:settings_data.get_item("custom_launch_items") references an external script file which is defined in the configuration file, part of the referenced file is below.  Notice that in this external file, since it is using the powershell dot executing method, it is able to reference the variable containing the personal settings data which was loaded through the main exe's load method - all without having to recompile the exe

if($script:personal_settings.get_item("disable_temp_group") -ne 1)


Invoke-Item $script:settings_data.get_item("temporary_groups_application")


Part II of this background tour of the Architecture will look at the scoping of the variables in the Toolkit, how to get the current function code out of the Toolkit and how to overwrite any of the functions in the toolkit