• Search

  • Pages

  • Archives

  • Categories

  • Meta

  • Reusing Functions in ARS Scripting

    20/11/13 7:08 PM

    Sometimes in scripting, I tend to reuse the same bit of code over and over again and it can cause the script being written to become overly large, or larger than it really has to be.  This is where powershell functions come into play.


    A function is nothing more than a reusable bit of code that is referenced by a name and possibly some variables that are passed into the function.


    An example of this is:


    function HelloWorld {


    write-host “Hello to the World!”




    And in the script, it would be called by simply referencing the name




    The function may be included in the body of a script and called directly and all works as expected, but what can we do if the function is utilized across multiple scripts without re-inventing the wheel each time?  Well, we can place the function(s) in a PowerShell script and just include that script or reference the function script within the new script.  In PowerShell this is called dot sourcing and is formatted like so:


    . c:\scripts\include.ps1


    Note:  The format is a period, space, and then the path to the script to include.  When dot-sourcing a script, all variables and functions are available to the console after the script ends.


    So, now we have the basics of that out of the way, the same idea can be used in Quest Active Roles Server (ARS).  Script modules within ARS can be created for a multitude of operations:


    • onPreCreate
    • onPostCreate
    • onPreDelete
    • onPostDelete
    • onPreModify
    • onPostModify
    • onPreMove
    • onPostMove
    • onPreRename
    • onPostRename
    • onPreGet
    • onPostGet
    • onPreDeprovision
    • onPostDeprovision
    • onPreUnDeprovision
    • onPostUnDeprovision


    Let’s just say, for all of the operations above, you had a need to write the date and time to the description field if the object was a type of User.  This could be a requirement for and easy to tell when the user object was last touched by the automation of ARS.


    The scenario above would be good use of a function and including this function with all ARS Policy scripts, then it could be called from all scripts.


    To accomplish this, first, we need to create a Library script within ARS.  A Library script is the only type of script in ARS that may be referenced from a policy script.  In the ARS console, expand Configuration, then Script Modules.  From here the Library script can be created, or a new Script Container can be made to house and organize the custom modules.



    I have a custom scripts container where I place all of my created scripts (Library and Policy).  Right click where you want to create a script, and select New->Script Module.  This will open the Wizard to create a new Script Module object.



    Enter a name for the new library, select your language of choice (this has been written around using PowerShell), enter a Description if so desired, and click Next.



    This page is where we select Library script.  As you can see by the explanation, this is exactly what we are looking for.  Click Next.



    The last page is just a confirmation, click Finish to create the new Library.

    In order to add functions to the new Library, locate it within the tree, click on it (you will see the right pane is blank), and either click the icon b1or press F4 to edit the script.

    Now, we create our function.  I will just show the finished code below:

    Function SetUserDescription {

    If ($Request.Class –eq “User”) {

    $dn = $DirObj.Get(“distinguishedName”)

    $Date = Get-Date -Format “yyyyMMdd-HHmmss”

    $Description = “User Modified by ARS on “ + $Date

    Set-QADUser $dn –Description $Description



    The code above checks the class, grabs the users DN, grabs the Date, builds the description text, and then sets the users description.

    Save the Library script by clicking the icon b2 or by pressing Alt-S

    We have a script Library with our function saved in it, now to use it within a policy script.

    A new Policy script can be created using the previous steps for the Library script, just select Policy Script in the second step.

    Follow the Library procedures for editing the script.

    Now we are in editing mode, let’s include our Library.  Click the icon b3 or press Alt-L.



    This dialog appears, and all that is required is to expand the container that the Library exists in and check the box next to the Library and click OK.  Note:  Multiple Libraries may be included at the same time with this dialog.

    After the OK button is clicked, code will appear at the top of your edit window that looks like the following:

    function onInit($Context)


    $Context.UseLibraryScript(“Script Modules/Custom Scripts/TestLibrary”)


    With this included now, you may reference any function that exists within that Library.  In our example, you would just reference SetUserDescription in order to call that function.

    function OnPreMove($Request)


    ***Do some stuff ***



    The above will execute the SetUserDescription function from the included Library script before a User is moved but after ‘stuff’ script commands execute.

    Once your Library is built up and assigned to Policy Scripts, you are ready to assign these Policy scripts to Provisioning Policies, Deprovisioning Policies, or Workflows within ARS.


    Author: Russ Burden, Technical Architect, LeadThem Security





    Posted by bc-admin | in ARS | Comments Off on Reusing Functions in ARS Scripting

    Comments are closed.