How to use Rules with InstallBuilder

Published on

The installation of your application does not have to be a rigid, linear sequence of actions. For example, maybe you need to copy certain files only if the target platform is Mac or Linux, but not if it is Windows. Or you may want to modify or add some content to a file, but only if it is needed (you don't want to duplicate configuration settings). Here's another example of common functionality: You may want to discard or accept user input depending on whether it meets certain criteria.

Rules in InstallBuilder allow you to determine when to perform certain actions depending on the circumstances, variables and user inputs that are involved in the installation. It allows you to set conditions related to an action or an action group at any step of the installation, and they will be performed only if the condition is met. You can set not only one, but a set of multiple conditions that can be evaluated with an AND/OR group logic statement.

This article will explain how to implement conditional rules in your actions, how to select the appropriate rule for each case, and how this can help you to optimize your project and avoid duplicating code.

If you don't already have InstallBuilder installed on your system, you can download the latest version from http://installbuilder.bitrock.com.

Now, let's begin!

We will start with GUI in our first, simple example for a fictitious commercial application for Windows. Imagine that you want to distribute your product offering with the option of installing it for a time-limited evaluation period, or installing it as a registered “Enterprise Edition”, depending on whether or not the user has a valid license key on his or her machine.

  • Your desired behavior is:

    • - Your product will be installed as an “Enterprise Edition” if the installer finds a valid license file, “product.lic”, in the user's desktop folder. If that is the case, the installer will report that it is deploying an “Enterprise Edition”.

    • - If a valid license file is not found on the user's desktop, the product will be installed as a “Trial Edition” and the installer will inform the user of that.

Of course, this is a very simple case, but it is a good example for demonstrating how rules can work for you. Now, start InstallBuilder and open the Demo project. To do so, use one of the following methods:

a) Go to [File -> Open Project -> From file…] and double-click on demo.xml file…

b) Click on the Open Project button at the toolbar (see the image on the left), and double-click on demo.xml file.

NOTE: It's strongly recommended that you preserve the Demo project for future testing purposes, so it is a good idea to save the project you're working on as a new one. For example, you can save it as 'myruleproject.xml'.

Now, click on the Advanced tab on the left side of the InstallBuilder GUI. This will show you all of the installation steps, components and distribution files/directories, and allow you to specify highly customized settings for your installer.

We want to check if there is a license file before deciding what edition (evaluation or enterprise) will be deployed, so select 'Pre-Installation-Actions'. This step defines the actions the installer must execute before the first page of the installer is displayed. Right-click the item and select 'Add'.

Now, we need a variable in which we will store a value that will depend of whether or not there is a license file found. We will call this variable 'edition_type', and it will store one the following values:

  • - trial: If there is not any license file found, it will be a 'trial' edition.

  • - enterprise: If the installer finds a license file, it will be an 'enterprise' edition.

Depending on which of the above values is returned, the installer will install the application as either an 'Enterprise Edition' or a 'Trial Edition'. So, how do you set the right value for the variable? The answer is: with InstallBuilder rules. We will set the variable with rules that will check if there is a license file present.

You can think about a rule like a condition that needs to be met to allow the related action to be be executed. If the rule is met, the action will be performed; if it isn't met, the action will not.

  • We need to set the value depending on which rule is met:

    • -Set: edition_type=trial if a license file is not found)
      • -Set: edition_type=enterprise (if a license file is found)

After selecting 'Add', we will find a new dialog window where you can select the type of action that you want to add to this step. We will select 'Installer Actions' on the left, and 'Set Installer Variable' on the right. Then press 'Ok'.

We will be presented with a new dialog window where you must enter the needed parameter for the action.

In this case, the 'Set Installer Variable' action will need the following parameter to work:

  • -Name: The name of the variable that we want to create. It will be 'edition_type'.

  • -Value: The value we want to store in the variable. It will be 'trial'.

After that, we will be returned to the advanced section of our project. Notice that there is a new item included as a Pre-installation action. This is the newly created Set Installer Variable action.

Now we will repeat the process and add the same action type, but this time the value for 'edition_type' will be 'enterprise'. As a result, we will get two items in the Pre-installation Actions trunk, each one with the two possibilities.

Notice that you can expand any of the actions that you have just created, and there is a parent node called 'Rules'. Here is where we will set the rule that must be met for the action to be performed.

Windows environment variables

Now that we are ready to add rules to our actions, there is another question to resolve: If the installer will look for a license file in the user's desktop, and the path to this location depends on the user's name and the Windows edition, how do we add the path? The answer is: with environment variables.

All operating systems, including Windows, have environment variables that help us to determine certain variable values and locations. If we read the Windows documentation, we will find that the environment variable called HOMEPATH will return the home directory of the current user. So if the user that executed our installer is named 'Joseph' , this variable will return something like: C:\Documents and Settings\Joseph.

InstallBuilder can read these environment variables for us and return the result. For this purpose we will use ${env()} to load the value of HOMEPATH:

${env(HOMEPATH)}

We are now able to set the location where we want the installer to look for the license file (the user's desktop):

${env(HOMEPATH)}/Desktop/product.lic

Adding the rules

Now, select the Rule node for the first action (edition_type=trial), and right-click to select Add. You will find a new dialog asking for the rule type. Select 'File Exists'. That allows us to check if there is a file present.

Then press 'Ok'.

We will get a new dialog window that asks for the path that points to the where the file would be stored if it exists.

In the field 'Path name' type:

${env(HOMEPATH)}\Desktop\product.lic

Remember to check the Negate option, since what we want is to set the value 'trial' to the variable 'edition_type' if the file does not exist.

Notice that now there is a new item in the Rules node for the first action, so this action will be performed ONLY if the file is not found at the given path.

Now try to add the rule for the second action. This action should try to set the value 'enterprise' to the variable 'edition_type' if the license file is found, so it will be equal to the previous rule, except for the fact that it is not negated this time.

As result, you will have two actions in the Pre-installation Actions folder, each one with its own rule. We have now finished the process during which the installer determines the properly value for the variable 'edition_type'. Let's check if it is all correct.

Adding an info dialog

Now that we have the actions and its rules, we need to create an action to show a dialog to inform the user which edition he or she is installing. For this, we need a Show Info Dialog.

Now that you know how to add an action, you can do it by yourself. Add a 'Dialog Action', type 'Show Info Dialog' just after the last action on Pre-installation Actions.

The text for this dialog will be: The installer will deploy the ${edition_type} edition on your computer.

Notice that the expression ${edition_type} will return the current value for the variable 'edition_type', which would be 'trial' or 'enterprise' in this case. Press 'Ok'.

Now we have three actions on our installer. The last one will be a dialog box that will report which edition will be installed.

We are ready to test the installer.

Testing the installer

To quickly test our installer, we can use the 'Test Run' button that is located in the tool-bar of InstallBuilder. Press it, wait for the build process to complete and the installer will start. Create an empty file on your desktop called 'product.lic' to test the way the installer responds depending on whether or not the file is present.

Of course, if you were to build an installer for production, you would want to check more than just whether or not a license file is present – you would want to confirm that it is actually valid. That can certainly be done using InstallBuilder, but is a topic for another how-to.

And now?

Here are some additional rules that you may find of use:

  • - Compare Text: Compares two values and check whether or not they are equal.

  • - Component test: Checks if a certain component is present in the installer.

  • - File Content Test: Checks if a file contains certain text. Very useful for checking configuration files.

  • - Host Validation: Helps you to check if a given host is valid.

  • - Platform Test: Checks to see if the target system is on your list of supported platforms.

  • - Process Test: Checks for the execution of a process in the target system.

  • - Regular Expression Match: Checks for a match between a given value and a pattern using regular expressions.

  • - Registry Test: Looks for certain keys/values in the registry. A must-know rule for Windows installers.

  • - User Test: Checks for the existence of a certain user in the system, or checks its password is valid.

  • - Windows Service Test: checks whether a service exists or whether it is running.