Script Based Triggers in FinalBuilder Server 7

FinalBuilder Server provides a set of triggers that start builds automatically based events, like the time of day, check-ins to a version control system, or changes to a file.

Version 7 adds script based triggers. These triggers run either an (Iron)Python or Powershell script, giving you ultimate of control over when your build is triggered.

Creating a script based trigger

From the FinalBuilder Server home page, create a new project or edit an existing one (I won't cover the details on that here).

Create a new trigger. Give it a name and set the trigger type to Script Based Trigger. Scroll down to the Scripting Options section of the page. You can choose the language of your script and enter it in the 'Script' box.

Triggering a build

An object is made available to both languages that allows you to interact with the build server. In Python, it is exposed as a module called Context, which you do not need to import. In PowerShell, it is exposed as a variable called $context.

The context object has 3 methods:

• SetTriggered(): This is the most important method of the Context object. Calling this method means that the build will be triggered
• AddTriggerOutputMessage(message): The string parameter passed to this method is logged in the build queue. Use this to provide information about the circumstances that triggered the build
• AddFileModificationItem(name, action, user, comment, type, version ): Adds information about a file that was involved in the build triggering. This is logged and also passed to FinalBuilder, for use in the Trigger Files Interator action
• ExecuteProgram(filename, workingDirectory, arguments): This method runs an executable under the context of user set to run the build. It returns an ExecutionResult object

Python

A stub Python module has been provided to allow you to test scripts stand-alone. The stub can be found at <FinalBuilder Server Install Dir>\Examples\Context.py.

The following simple script executes a program and triggers the build if the program exits successfully. It uses Context.py for stand-alone testing:

import Context
#copy from here

import sys
sys.path.append('c:\\path\\to\\my\\custom\\modules')

import myModule
def TriggerTest():
    myModule.myFunc()

    app = 'cmd.exe'
    wd = r'C:\Windows\System32'
    result = Context.ExecuteProgram(app, wd, '')

    if result.ExitCode == 0:       
        Context.SetTriggered()
        Context.AddTriggerOutputMessage('%s successful, build will be triggered' % app)
        #Context.AddTriggerOutputMessage('Output from %s: %s ' % (app, result.StdOut))
    else:
        print 'Build will not be triggered'
        print '%s failed with return codee %d: %s ' % (app, result.ExitCode, result.StdError)

TriggerTest()

#copy to here
print Context.Output()

Things to note:

• Only the code between the copy from/copy to comments would be copied to the Trigger script
• You can import IronPython modules, such as time. To do this you will need to install IronPython and specify the install directory in the trigger
• You can use sys.path.append() to add any other directories from which you would like to import modules
• 'print' statements from the last run will appear under the Script area of the trigger

PowerShell

Triggering a build with PowerShell is a simple as calling 

$context.SetTriggered()
$context.AddTriggerOutputMessage("Triggered by PowerShell!")

To test your script before adding it to the trigger, you can load the Trigger and TriggerExecutionContext objects from FinalBuilderServer.Build.dll:

[reflection.assembly]::LoadFile("FinalBuilder Server Install Dir>\FinalBuilderServer.Build.dll")

$trigger = new-object VSoftTechnologies.FinalBuilderServer.Triggers.ScriptBasedTrigger

$context = new-object VSoftTechnologies.FinalBuilderServer.Triggers.TriggerExecutionContext($trigger)

Just Remember

Your scripts should be able to do just about anything that's normally possible in IronPython or PowerShell. Just keep a couple of things in mind:

• triggers are designed to be low-overhead and short-lived: you're best off keeping them as simple as possible
• the script will run in the context of the user that runs the build (set at the project or server level). That user will need access to any external resources that the script references.