User's Guide - Chapter 2: The Project Wizard
Every journey begins with a first step, and TrueUpdate makes this step as painless as possible. With the built-in project wizard, creating professional product updates is as easy as filling in the blanks and clicking Next. This chapter will introduce you to the easy-to-use TrueUpdate project wizard.
Everything has to start somewhere. In TrueUpdate, the design process starts with the creation of a new project.
A project is simply the collection of scripts, screens, settings and everything else that goes into building an update. For example, each project will contain the scripts and screens that will be built into the TrueUpdate Client application as well as those that will be contained in the server files. The settings for all of the scripts and screens in a project are stored in a single file, known as the project file.
When you start a new project, TrueUpdate’s project wizard walks you through the first few steps of project creation. This helps you get your project started quickly without missing any of the basics.
Let’s open the TrueUpdate program and start a new project.
Use the Start menu to launch the TrueUpdate program.
You’ll find TrueUpdate under:
Start > Programs > Indigo Rose Corporation > TrueUpdate 3.0
The Welcome dialog appears whenever you run TrueUpdate. It not only welcomes you to the program, it also lets you easily create a new project, open an existing one, or restore the last project you worked on. (Restoring the last project automatically opens the project you were working on the last time you ran TrueUpdate.)
When you click on "Create a new project," the Welcome dialog closes and the project wizard appears.
First, the project wizard asks you for three pieces of information related to your project. Simply enter your company name and product name in the appropriate fields. Additionally, you may specify a unique server file encryption key; however, the randomly generated default key is unique to each project and is typically sufficient.
When you’ve entered all your information, click Next to move to the next step in the project wizard.
Tip: At any step in the project wizard, you can click Cancel to go straight to the program window with all of the default project settings untouched (i.e. to start with a "blank" project).
The next step in the project wizard is to specify which type of user interface your TrueUpdate Client will use.
The most common update user interface is the default Wizard style. A Wizard style interface presents the user with a series of screens which they can navigate through by clicking Next and Back buttons. Wizard interfaces are considered very user friendly because they present and request information in discrete, guided steps, which makes the overall process easier for the user to understand.
The other two interface styles are Dialog and Silent. A dialog user interface uses popup dialogs or "message boxes" as opposed to screens to guide the user through the update. A silent update runs entirely in the background, and has no user interaction whatsoever.
The last option in this step allows your TrueUpdate Client to run silently until an update is available. Once an update is available, the client will continue in whatever style you have chosen (Wizard or Dialog).
This step allows you to configure how your update will look. Once you’ve selected your project theme, click Next to proceed to the next step.
TrueUpdate supports multilingual updates. In this step, you can select which languages you want your update to support by checking them off. As well, you can select the default language to be used in the event that the user’s system employs a language you haven’t specifically accounted for.
Two things happen when a language is supported. First, TrueUpdate will use the text from that language’s message file (if one exists) for the update’s built-in messages when that language is detected at run time. (If a message file doesn’t exist for a particular message, the default language’s message file will be used.)
Second (and more important), you will be able to localize the text in your project for each supported language. For example, if you choose English, French and German as your three supported languages, you will be able to enter different English, French and German text on your project’s screens. This is done by simply choosing a different language from the language selector, which appears wherever there is text that you can translate in your project.
Note: Only supported languages will appear in the language selector; you will only be able to select a language on a screen if that language was "checked" in the list of supported languages.
Once you’ve selected the languages you want to support, click Next to proceed to the next step.
TrueUpdate supports a variety of file transfer protocols. This step allows you to specify which protocol your update will employ.
The first option is to use the standard hypertext transfer protocol (HTTP). This protocol was designed for accessing files on a web server from your local system. This is the same protocol that Internet Explorer uses, and is generally the easiest method to use. Since it uses port 80 by default, it’s also the most likely method to be allowed across a user’s firewall; chances are that if a user can browse the Internet from their computer, they’ll be able to run your update.
The second option is to use the secure hypertext transfer protocol (HTTPS). This is essentially a "secured" version of HTTP that uses the Secure Sockets Layer (SSL) to perform the data transfer in a more safeguarded fashion. It operates on port 443 by default.
Note: In order to use the HTTPS protocol, you must have a secure web server to connect to. You can’t use HTTPS to connect to a regular web server; you can only use the HTTPS protocol if your web server supports it.
The third option is to use the file transfer protocol (FTP). This protocol was designed for exchanging files over the Internet, and supports file transfers in both directions, i.e. downloading and uploading. (It is commonly used to upload web page files to the web server that will host them.) In order to transfer files to or from an FTP server, you must logon to it by providing a user name and password. Many FTP servers provide public access to their files by accepting a "guest" logon; this is usually referred to as "anonymous ftp." The FTP method transfers files over port 21 by default.
The fourth option is to copy the files over a local area network (LAN). This method is ideal if your update will be distributed within your organization, as transfer speeds are quite high. However, it cannot be used to download the configuration files from a remote site (over the Internet). To use the LAN transfer method, the client must have direct access to your network.
For this walkthrough, select the standard HTTP transfer method, and click Next.
TrueUpdate needs to know the specifics of the server from which your client will download the configuration files.
Fill in the URL to the folder that will contain your TrueUpdate server files.
The Timeout setting refers to the amount of time in seconds that the TrueUpdate Client will wait with no reply before giving up on the server and returning an error.
The Port field allows you to specify a different communication port if your web server doesn’t use port 80 (the standard HTTP port). Use this field to specify which port your server is accessed by.
You can also use basic HTTP authentication to connect to your server, if required. This allows you an additional layer of security by requiring a valid username and password in order to download the server configuration files. If your web server supports basic HTTP authentication, select the "Use authentication" option and insert the authentication username and password.
This step allows you to specify the prefix that your server files will use. This is a useful step if you have multiple products and would like to host your products in the same folder on your web server.
For your convenience, TrueUpdate can automatically upload the server configuration files for you whenever you build your project. This feature can be a helpful time saver but is, of course, completely optional. You can always upload the configuration files to your TrueUpdate server locations on your own --by using your favorite FTP program, for example.
The first option allows you to take care of uploading the server configuration files on your own, separate from TrueUpdate, or to configure the upload automation later. (You can add automatic upload locations at any time on the Upload tab, which you can access by choosing Publish > Settings from the program menu.)
The second option will automatically transfer your files by FTP, and the third option will transfer your files by SFTP (secure FTP). These options are useful when you need to upload the files to a web server, as we will be doing in this walkthrough.
The last option performs a simple file copy and is useful if you selected LAN as your download method.
Since we chose to download the server files from an HTTP server earlier in this walkthrough, it would be convenient to have TrueUpdate upload the configuration files to that web server for us. Uploading files to a web server is normally done via FTP, so select the FTP option and click Next.
This step allows you to specify where to upload the TrueUpdate server configuration files.
Note: Though we are uploading the server files via FTP, the client will access them via HTTP. Since HTTP is strictly a download protocol, we need to use a different protocol to upload the files to the web server.
In this step, you need to specify the full address of the folder where the server files need to be uploaded to. This will consist of the FTP server address and the full path to the folder on your FTP server. You can also configure the timeout of your FTP server and the port to be used when connecting.
Lastly, you must enter the username and password that is used to access the FTP server. Be sure to use a username with appropriate access rights, as the TrueUpdate design environment will be uploading files to the server.
The passive mode option is useful when connecting to an FTP server from behind a firewall. When you connect to an FTP server normally, the server attempts to open a second connection back to your computer. If you are behind a firewall, this connection will often fail. (Most firewalls object when external systems attempt inbound connections.) Using passive mode, the FTP server will wait for your computer to open both connections, thus avoiding the objectionable behavior. The FTP server must support passive mode connections in order for this method to work, but it is a widely supported option.
Once you have entered all of your information, click Next.
Since you are creating an update for an existing product, TrueUpdate needs to know how to determine which version of your software is installed on the user’s system so it can decide if a newer version is available.
There are basically three ways to determine which product version is installed. The first is to inspect the value of a registry key. This is an excellent option to choose if your installation program stored some kind of version-identifying value in the registry. For example, many installation programs create a registry key containing the version that is being installed so that other programs can easily determine the current version. This is a popular method supported by most installation tools. For example, Indigo Rose’s Setup Factory allows you to easily create and modify registry keys during an installation.
The second option is to use specific file information such as the date a file was last modified. In fact, many files such as exe’s and dll’s contain version information that can be read using this option. This method is useful if the installer stored no additional version information (for example, if the product didn’t use an installer at all). In that case, you may wish to use the version information stored in a primary file such as the software’s main executable (if it has one).
The third option is to read values directly from an INI file. This is similar to reading a value from the registry, but the value is retrieved from an INI file instead. The INI file would have either been included with the product or created when the product was installed. (Setup Factory is also capable of creating and modifying INI file entries.)
Note: Whether to store version information in the registry or in an INI file is largely a matter of preference. However, your TrueUpdate project needs to use the same method that was chosen for your installer. For example, if your installer stored the installed version in a registry key, your update won’t work if you tell it to get the version from an INI file.
There is a fourth option that allows you to skip this step for now. This is useful if you would rather configure this option later, or if, for example, you want to perform the update every time the update is run, regardless of the version currently on the user’s system.
For this walkthrough, select the File Information option and click Next.
This step allows you to specify both which file and which attribute should be checked in order to determine which version of your software is installed.
There are five types of file information that can be checked:
File Version
The "file version" stored in the file. This is normally the version number of the file itself.
Product Version
The "product version" stored in the file. This is normally the version number of the product that the file belongs to.
Creation Date
The date and time when the file was created.
Modified Date
The date and time when the file was last modified.
CRC Value
The CRC value of the file. The CRC value serves as a digital "fingerprint" which can be compared to the CRC value of a known version of that same file in order to determine whether the two files match.
Select the Product Version option, and click Next.
In the previous step, we decided to check a specific file for its product version. In this step, we will specify a value to compare that product version to. This essentially lets you specify the target version for your update--the version that you want to update the software to. This is the value that your TrueUpdate Client will compare the installed version to in order to determine whether a newer version is available.
You can click the Get File Version button to retrieve the version information from a specific file on your system. This allows you to quickly get the most up-to-date version information from your newest software.
This step controls how your software will be updated when the TrueUpdate Client determines that an update is available. There are two options. The most common method is to have your update download an executable patch file (or installer) and run it. Or, if you prefer, you can select a custom update method from a list of pre-defined templates.
Select the Single installer/patch file option, and click Next.
Before the client can run the installer or patch file, it needs to download it from somewhere. This step allows you to specify what method the TrueUpdate Client should use to download the file.
The same options exist as in step 7, where you specified what method to use to download the server configuration files. Select the HTTP method and click Next.
As in step 8, this step allows you to specify how the TrueUpdate Client will interact with your web server. Only this time, instead of specifying where the client can find its server configuration files, the settings determine where the client should get the executable installer or patch file that will actually update the installed software.
You must specify the exact path to your patch file, as well as the timeout and port to be used. Additionally, you may use a username and password to connect to the server if it supports basic HTTP authentication.
Once you have specified how TrueUpdate will connect to your web server, click Next.
This step allows you to tell the TrueUpdate client what to do with the patch once it has been downloaded.
You must specify a location to download the patch to. Be sure to specify a location that the users will have write access to, or the TrueUpdate Client will not be able to save the file. If the users do not have sufficient access rights to create a file in that folder, the download will fail.
You also have the option of specifying command line arguments to use, and whether the TrueUpdate Client should wait for the patch executable to return before continuing. Also, if your patch executable returns a result code, you can specify a return code that indicates success.
This step allows you to review everything you have configured before you create the project. Review the information presented, and either move back through the wizard to make any changes, or click Finish.
After you click Finish, the project wizard will close and the design environment will appear, complete with scripts and screens configured with the settings you chose in the project wizard.