August 28, 2009

Surround SCM Triggers - Executables

Surround SCM
Automation is a key part of any software configuration management tool. Without automation you must manually perform tasks, which only increases the chance of error. Surround SCM includes triggers that allow you to automate many actions, such as sending e-mails, changing a workflow state, and preventing actions under specific circumstances. Most of the actions available in triggers are visually oriented. For example, to send an e-mail you can select the recipient(s) from a list, configure the e-mail template, etc. However, inevitably you will have needs beyond what is offered out of the box. In those situations you may want to consider running an executable through the trigger mechanism. So what exactly is an executable? An executable is anything that you can launch through the command line. It is not limited to files with an .exe extension. It could be a .bat file, a .pl file, a .jar get the idea.

Things to keep in mind

It is very important to remember that the Surround SCM Server runs the executable. Keep the following in mind when you set up the trigger: Location of executable: The location entered in the trigger has to be accessible by the Surround SCM Server. One way to approach this is to ask yourself: "If I logged in to the machine running the Surround SCM Server using the same credentials that the Surround SCM Server uses, would I be able to access the file?" If the path to the executable is on the same machine, there shouldn't be any issues. Accessibility may be an issue if you want to store the executable on another machine. Permissions: The Surround SCM Server must have the necessary permissions to execute the executable and any of the executable's actions. The permissions are determined by the user account running the Surround SCM Server. One way to approach this is to ask yourself: "If I logged in to the machine running the Surround SCM Server using the same credentials that the Surround SCM Server uses, would I be able to perform the same actions that the executable is supposed to perform?" Provide the necessary information: For some files, like .exes, you only need to enter the path to the file. For others, you may also need to include the binary that runs the specific file types. For example, let's say your executable is a .jar file or a Python script (.py). In these instances, you also may need to pass the path to the Java or Python binaries, like this: "C:PythonPython.exe" "" or "C:Program FilesJavabinJava.exe" -jar " "C:SurroundScriptsUpdate.jar" Attention Linux Users: If your Surround SCM Server is running in Linux, remember to mark the file to be executable. You could use something like "chmod +x <filename>".

Getting Started

Keep it simple. Do not start out by writing a complex script and expecting it to work right away. I used to work as a Seapine technical support specialist. When a user would contact us for help with triggers, I would first have them run a very simple batch file. Something like: echo "Hello World!">C:test.txt I would then instruct the user to perform the action that should cause the trigger to fire. If the test.txt file was created on the C: of the server machine, then we knew two things:
  1. The trigger was configured correctly
  2. The server was able to launch the executable
Try this yourself. If the test.txt file is successfully created then you can proceed with more complex executables.

Take Advantage of What's Available

You may not be aware of this, but when Surround SCM launches an executable through a trigger, it exposes certain information as environment variables. The most up to date list is found in the Surround SCM user guide, but you can also find it here.

Post-Event vs. Pre-Event

You have the option of running pre- and post-event executables.  You may be wondering about the difference between them. Pre-Event When an executable is launched pre-event, Surround SCM waits for the executable to finish before allowing the event to complete. If the executable returns an exit code of 0, Surround SCM allows the event to complete. Any other exit code will cause the event to be prevented. In fact, if you pass a message to the console, it will also be displayed to the user in a message box. Post-Event When an executable is launched post-event, Surround SCM launches it after the event is completed, so it has no effect on the event triggering it. Surround SCM also does not wait or keep track of this process. Which One Should You Use? This depends on the purpose of the trigger. Pre-event triggers are mainly used if you need to prevent something or access information before the event is committed. For example, the local file about to be checked in. Otherwise, post-event is the way to go.

Practical Approaches

So now that you know more about executables, what can you do with them? Here are some examples of how current Surround SCM users use triggers:
  • Copy files to a network location after check in.
  • Integrate with a bug tracking tool (not TestTrack Pro) or another third party tool.
  • Launch a build.
  • Prevent check ins when the comments do not match certain criteria.