This lesson teaches you how to install, update, and troubleshoot a Partner Platform user installation. This includes the Map Viewer, the face of the Partner Platform and the part most users will see.
All examples will use a provided training demo installation. If you are already a Partner customer, map data and other details will vary from your own configuration.
This tutorial starts the Course: Partner Platform Fundamentals. You MUST complete this tutorial, at least installing the training demo, to follow the exercises in later tutorials.
None! This is a beginning tutorial.
You do need a PC or laptop, web browser, and Internet connection, but if you’re reading this you’re probably good to go.
Partner Update refers to the program and a subsystem for distributing changes to all installations at a site. Changes to configuration, data, or program files made to source installations are propagated down to destination installations using an incremental and largely automated process. The various types of installations form a hierarchy, with each descending level containing more specific configuration.
Installation uses the same process, so is really just a special case of updating in general.
Source installations are made visible on websites, and all updates occur using standard web protocols. The installation page itself is a simple web form. Thus you can instruct someone to install the software by sending them a link via email, or on a web page, as we will do in this tutorial. However, this installation page is only necessary for the initial install, or when you need to change versions, or use a different source site. Routine updates are handled automatically whenever the user starts the program, or can be triggered by scheduled tasks.
For a more detailed description of the update process, see the corresponding section in the Partner Development Manual.
The installation process for this course has two step. First we install a training demo of the Partner Basic Platform, which we will use for the remainder of the course.
Open a new window or tab in your web browser and point it at the following URL: http://download.partnersoft.com/courses/PartnerPlatformFundamentals/. Most browsers let you right-click on the link to select opening it in a new window or tab.
You will see the following page:
TODO: screenshot of installation page
The installation form is designed to be as simple as possible, to eliminate end-user error. It is actually configurable for your site, so that you can further constrain the options provided. This is a typical setup.
The link to “Install Java for Windows” is necessary if your Windows installation does not include a reasonably recent Java runtime. Clicking on it downloads an executable which you can then run to install Java. You should only need to do this if you get an error or if the installation program doesn’t launch for some reason. The Partner training computers already have Java installed, as do most newer computers.
For most customer installations, all you need to do is press the “Standard User Install” option. However, for this tutorial, let’s change the destination to c:PartnerBasicTraining. All files will go under this directory.
This is what your form should look like before pressing “Custom Install”:
TODO: screenshot
Once you have the directory set as shown, click the “Custom Install” button.
Partner Update uses Java Web Start, a facility for running Java code from a website without having to download and pre-install it on your computer.
You may see a warning window like this:
TODO: screenshot
Say “Trust” or “Always Trust”.
You will then see the “Partner System Update” window, which has a number of status messages and a progress meter at the bottom.
TODO: screenshot
This window will run for awhile, then go away on its own if it’s successful. Going away is Good, and normal.
You will then see a dialog box that says “Partner update complete!”
TODO: screenshot
You can choose to either “Start Partner” or click “Done”. Go ahead and choose “Done” for this exercise.
The software should now be installed to the directory you selected, and icons should have appeared in your start menu and on your desktop. Double-click the Partner icon to start the software.
Some antivirus and firewall applications, will block Partner from opening the first time. Instruct the antivirus or firewall software to stop blocking Partner.
You should see something like this:
TODO: Map viewer screenshot
If you don’t see any maps right away, try clicking the Home button.
User-specific preferences are controlled by the Edit Config program, also known as “Edit Preferences” or just “Preferences...”.
This is available as a standalone program and also as a menu action in the Map Viewer. Go to the Platform menu and select Preferences... to open it.
There are quite a few settings available. For purposes of this tutorial, the most important tab is the one labeled “MapSpace”:
TODO: preferences screenshot
Ensure that all the mapsets are turned on, then click the “Apply and Restart” button.
The Update program depends on files in the update/ directory of your install. Go to the install (on Windows, c:PartnerBasicTraining) and look at it. You should see the following file structure:
TODO: screenshot of file structure
Look in the update/ directory. It has two subdirectories, info/ and packages/.
The update/info/ directory has several text files. Take a look at each to see what they contain. It should be fairly obvious from the name and contents what each one does.
One important file, for example, is UpdateSource.txt. It should have the following in it:
http://download.partnersoft.com:80/courses/PartnerPlatformFundamentals/
This is the last place that the software was installed from, and this is where the automatic update will check for changes.
The update/packages/ directory contains the actual compressed archive files on a server (source) installation. For a User installation like the one we just did, it only contains the checksum files (*.checksum). These checksums are compared to the ones on the source to see if anything changed.
The logs directory is where log files go, and update has its own, named... update.log. Look here if you have problems, especially if they are mysterious. Pay special attention to the URLs and other things, since your problem may be due to updating from the wrong place.
The Map Viewer checks on startup for any file updates from wherever you installed it from. It remembers the website address in the file update/info/InstallSource.txt. It uses the checksums in update/packages/ to see if anything changed.
Since our source is not going to change while we’re working on this tutorial, we will simulate a change. Close the map viewer, and open up the file update/packages/customer config.checksum in a text editor. It should have a single big number in it. Change the number and save the file.
Then, start the Map Viewer again. You should get the “Updates Available” dialog:
TODO: screenshot
The dialog gives you the option not to update, in case you’re in a hurry or for some other reason don’t want to change your install. But generally you do want to update, so you hit OK. The “Partner System Update” program should run again, this time much faster since it’s only updating a single, small package. Then, the Map Viewer should start again. Isn’t that convenient?
You can install a different version of Partner on top of an existing install. Note that this resets the source for your updates to the Partner website, which means you won’t get your map updates from your original install. So, this is only recommended for test installations (like this), or, once you’ve tested a version, for updating the MasterInstall on your hub.
Here’s how it works: you go to a different website and use the same installer form you did for the initial install. This is the same process you use if you change servers (e.g. if the IP address changes for some reason).
Point your browser at: http://update.partnersoft.com/4.14/
This is a generic, distribution-level install page, so you’ll need to use the “Custom Installation” section at the bottom. Enter your install directory (c:PartnerBasicTrainingon Windows) and select User as the type. Then click the “Custom Install” button.
TODO: screenshot
The (hopefully familiar now) Partner System Update window will appear again and update your installation to this version.
When you change the version of an installation, you should also generally update the modules to match.
You’ll also need to update the installed modules to match the new version of the platform. Make sure the Map Viewer is closed and run the program os/windows/tools/UpdateModules.bat to do this. It displays a log as it goes through each installed module, downloads a zipped copy matching your installed version, and replaces the installed files with those in the zipfile.
If we wanted to revert to the original version and install source, pointing our browsers back at the tutorial page and re-running the installation will fix it. But let’s try something different, to illustrate how simple the configuration for Update is.
Open up the file update/info/UpdateSource.txt within your installation. If you did the above exercise, it will contain the following:
http://update.partnersoft.com:80/4.14/
Edit it to match our original source:
http://download.partnersoft.com/courses/PartnerPlatformFundamentals/
Now run Update by double-clicking the icon or running (in Windows) the batch file os/windows/programs/Update.bat.
Now our installation is back to its original form and with the original update source set.
This illustrates an important concept: Partner configuration files are simple, are usually in text formats, and don’t generally require special tools to read or edit them. This is a very useful property when problems occur - which they do all too often with any complex software.
Not that there are any bugs in the Partner Platform. It’s perfect!
If you want to schedule updates to run unattended, set your scheduler to run the file os/windows/terminal/partner-update.bat in your Partner installation.
Update is designed to work well in most situations and, when problems occur, to fail in a reasonable fashion without messing up the installation. For example, it first downloads all necessary files before attempting to unpack and install them.
Networks and computers are unruly beasts, though, so problems do occur. Here’s what you do.
Always remember that you can run Update by itself through the desktop icon, Windows Start menu, or by directly running os/windows/programs/Update.bat. This should work even when the Map Viewer is otherwise broken.
Most of the time, problems are caused by intermittent or interrupted network connections. This breaks the download process and, if Update can’t download the needed files, then it can’t continue.
When that happens, try just running it again. This won’t hurt anything and may work fine. Update is designed to pick up where it left off.
If running it again doesn’t help, check your network connections and try running it once more. Perhaps the network is really bad, and just needs extra tries?
Read logs/update.log and see if it holds any clues. It should provide a clear message as to what happened - network error, out of disk space, etc.
Downloaded files are stored in update/download/ before being unpacked. Removing this directory signals to Update that it needs to start over and re-download them.
There is rarely any need to delete and re-install a Partner installation from scratch. Indeed we don’t recommend that, because deleting the whole install may remove other important files such as user-specific settings and data.
Generally it is just as good to re-install the various packages. Checksums for these packages are stored in the directory update/packages/. Removing this directory signals to Update that it needs to re-install all packages from the server.
Windows security, including UAC, firewalls, virus checkers, and other software, may interfere with the Update process. Check any of these that are on and ensure that they are not blocking access to the installation directory or to Partner Update.
Using general-purpose IT diagnostic tools, check the network between the client computer and the server, and check both
If none of the above fixes the problem, there is a serious and/or odd issue happening. Any customer may contact us at any time, but most often we will start by doing the items above anyway. But if none of those are successful then most likely we will have to roll up our sleeves and get our hands dirty working on it.
Hopefully you’ve learned that:
When troubleshooting: