Overview
The u3importer is a command line utility found in the util directory of the Urchin distribution. This utility allows for the importing of report configurations from an existing Urchin 3 config file as well as the data associated with each Urchin 3 report. u3importer has 2 modes. When run in interactive mode without any command line arguments, for each Report Block directive in the Urchin 3 config file the utility will create an Urchin 4 Profile, Log Source, and Task, and it will convert a copy of the Urchin 3 databases into Urchin 4 format and move them into their appropriate location in the Urchin 4 distribution. In command line mode using the -c option (explained below, only available in Urchin 4.105 and later), u3importer will simply take Urchin 3 databases and import them into new Urchin 4 database files without making any changes to the Urchin 4 configuration.
Important Note: The import utility must be run on the same operating system platform that created the Urchin 3 report data. It is unable to read and convert data created on a different operating system platform and attempting to do may cause unexpected termination of the utility. If you wish to upgrade from an Urchin 3 installation on one operating system to a new Urchin 4 installation on another platform type, you should first install a temporary copy of Urchin 4 on the old platform. Next, run the u3importer to create an interim Urchin 4 configuration and profile data. Since the resulting Urchin 4 profile data is platform-independent, this data can then be moved over to your permanent Urchin 4 installation on the new platform. Please note that it is not necessary to license the Urchin 4 distribution on your old platform in order to use the u3importer utility.
Procedure
When upgrading from Urchin 3, u3importer should be run before creating any new Urchin 4 profiles, if possible, since it must create a new profile for each Urchin 3 report it reads. The utility will not add data to an existing profile. Instead if a profile of the same name as it is trying to import exists, it will create a similar name with the number 2 appended to it and import the data into that profile. Therefore, it is strongly advised to run u3importer before normal operation begins under Urchin 4. It is also recommended to disable the automation of any existing Urchin 3 processing, so that new log files are not discarded or lost during the upgrade process. This will also ensure that the Urchin 3 data is not changing while running u3importer to import your databases.
To launch the u3importer in interactive mode do the following:
UNIX
telnet, ssh, or open a command tool or console window on the system where Urchin 4 is installed. Change directory to the Urchin 4 util directory, and execute u3importer like so:
./u3importer
Windows
On the system where Urchin 4 is installed, open a command prompt by going to Start->Run..., enter "cmd" and hit Enter. Once the DOS shell window launches, type:
C: cd \Program Files\Urchin\util u3importer.exe
Step 1: Locate the Urchin 3 configuration
The u3importer utility will prompt for the location of the Urchin 3
configuration file. A suggested location is provided. To accept the
suggestion, simply press return. Otherwise, enter the complete path
to
the config file located in the Urchin 3 folder. Wherever
Urchin 3
was
installed, there should be a config file located in that
Urchin 3
folder.
On Unix systems, this could be /usr/local/urchin3/config. On Windows
systems,
this could be C:\Program Files\Urchin3\config. If you cannot find
the Urchin3
installation, please contact your system administrator for details.
Step 2: Import Urchin 3 configuration profiles
Once the utility locates the Urchin 3 configuration, it will list all
of the sites that exist in the configuration and prompt you for which
ones to import. To
import all profiles, press enter. To import only select profiles,
type Y
or N as each profile is prompted. Before continuing to the
next
step, you
may verify that the configurations were imported correctly by
inspecting the
Urchin 4
Configuration interface.
Step 3: Import Urchin 3 data
After importing the configurations, the utility will then prompt to
import the
data associated with each profile. Importing the data will allow you
to view
Urchin 3.x historical reports under the new Urchin 4 interface. To
import
data for all profiles, press enter. To import data for only select
profiles,
type Y or N as each profile is prompted.
Command Line Mode (Urchin 4.105 and later)
In command line mode u3importer simply converts Urchin 3 databases and creates Urchin 4 databases. It is up to the user to make sure the Urchin 4 databases are located properly within the Urchin distribution and that the necessary Profiles, Log Sources, and Tasks are created to fully configure the site. To launch u3importer in command line mode and avoid having to interact with the dialogs, use the -c option like so:
u3importer -c /path/to/urchin3_udata /path/to/urchin4_databases
The path to your Urchin 3 data should point to the same directory path as shown in your Urchin 3 config file ReportDirectory directive for a given site. The path to the place to create your Urchin 4 directory can be anywhere. But if you want it to automatically become a part of your Urchin 4 configuration when you later add a profile for a site, you should make the path point to the data/reports subdirectory of your Urchin distribution. As an example, if you have a site named test.urchin.com in your Urchin 3 configuration, then in the report block for that site will be ReportDirectory directive similar to:
ReportDirectory: /www/test.urchin.com/
Assuming your Urchin 4 installation is in the default location of /usr/local/urchin4, then to convert the Urchin 3 databases for this site and have them put in the proper location in your Urchin 4 installation, you would run the following command:
u3importer -c /www/test.urchin.com /usr/local/urchin4/data/reports/test.urchin.com
In a scripted environment after running this command you would typically use uconf-import to create a Profile, Log Source, and Task to complete your migration for this site.