Taurus Software
   

Google Analytics Installation

 

Taurus Software's Warehouse program can access data from Google Analytics, however getting it working can be tricky because it requires software from several different vendors. This page documents the steps required for Warehouse and DataBridger Studio to access Google data.

 

Contents
 

0

Prerequisites
 

0.1

Google Analytics Setup
 

0.2

Setting Up Access
   

0.2.1

Login to Google Developers Console
   

0.2.2

Create a New Project
   

0.2.3

Name the New Project
   

0.2.4

Setup API Access
   

0.2.5

Get Your Credentials
 

0.3

Google Analytics View ID
 

1

System Requirements
 

1.1

Warehouse
   

1.1.1

The WHGAITMS File
 

1.2

Java
   

1.2.1

Java on Microsoft Windows
   

1.2.2

Java on Unix/Linux
 

1.3

Google Analytics Java Libraries
 

2

Steps to Access Google Analytics
 

2.1

Checklist of requirements
 

2.2

Set up wh.ini
 

2.3

Running a Test Script
   

2.3.1

Request for Permission
 

2.4

Setting up DataBridger Studio
 

2.5

Setting up the Warehouse Server
 

3

Troubleshooting
 

3.1

Checking Java
   

3.1.1

Checking Java on Microsoft Windows
   

3.1.2

Checking Java on Unix/Linux
 

3.2

Checking the WHGAITMS file
 

3.3

Checking the Google Libraries
 

3.4

Troubleshooting Warehouse Scripts
 

3.5

Checking the Warehouse Server
   

3.5.1

Checking Java on a Warehouse Server
   

3.5.2

Checking Google access to a Warehouse Server
   

3.5.3

Checking Google Script access to a Warehouse Server
 

0 Prerequisites

 

This section lists the tasks that must be completed before DataBridger can access Google Analytics data.


  • 0.1 Google Analytics Setup

    Before you can use Google Analytics data, the Google Analytics setup process must be completed.

    0.2 Setting Up Access

    Setting up access to your Google Analytics data is a multi-step process.  Follow the steps below:

    0.2.1 Login to Google Developers Console

    Go to the Google Developers Console and login using your Google login.

    0.2.2 Create a New Project

    Create a new project by clicking on "Project" in the drop-down menu near the upper left of the screen and then selecting "Create project" from the menu.

    0.2.3 Name the New Project

    Enter a project name for the new project.  This may be any name such as: TaurusAccessProject

    Click the Create button. It can take 10 seconds or longer for Google to create the project. The status is displayed in the lower right of the browser window.

    0.2.4 Setup API Access

    Enter the Google API Manager by opening the menu on the upper left of the screen (click the three little lines).

    While in the API Manager, click Library on the left to display all API's.

    Under the list of Other popular APIs, click Analytics APIs.

    Click Enable at the top to enable the Analytics API.

    0.2.5 Get Your Credentials

    The credentials for the project must now be obtained. DataBridger requires access to the Analytics API so this must be enabled. Click Credentials at the left of the Developers Console.

    Click Create Credentials, then select OAuth client ID.

    Click Configure consent screen.

    Fill in the consent screen. Only the email address and product name are required The product name may be any name such as: TaurusAccessProduct

    When done with the consent screen, click Save

    Back in the Create client ID screen, select Other for application type. A client name is now are required. This may be any name such as: TaurusClient

    After entering a name, click Create. After creating the client ID, your credentials are displayed.

    IMPORTANT: Save the client ID and client secret by copying and pasting the to another file. These will be used later as your login and password in DataBridger Studio.

    After saving your client ID and client secret, click OK.

  • 0.3 Google Analytics View ID

    Google Analytics requires a View ID to access Google Analytics data. The View ID is obtainable from Google by logging in and going to the Google Analytics Home page. Click on Admin at the top and you can view your Account, Property and View settings. Click on View Settings to get your View ID needed to access Google Analytics. Administration can be somewhat confusing because of the flexible account structure. See Google Analytics account structure.

1 System Requirements

 

This section lists the items that need to be acquired before Warehouse can access Google Analytics data.


This assumes that your web pages have been setup to collect Google Analytics data and that data is available on Google's servers.

 
  • 1.1 Warehouse

    Warehouse release 3.04 or later from Taurus Software is required. DataBridger Studio version 5.4 or later can also access Google Analytics data. These may be obtained from our DataBridger download site (login required). You should also be aware of your installation directory. On a Microsoft Windows system, this will usually be:
     
      C:\Program Files\Taurus\Warehouse

    Warehouse installation directory
      C:\Program Files\Taurus\DataBridger

    DataBridger installation directory
     
      C:\Program Files (x86)\Taurus\DataBridger

    DataBridger Studio on 64-bit Windows
     
    On Unix/Linux systems, the installation directory is where the administrator installed the software and may be something like:
     
      /var/taurus/warehouse

    Warehouse installation directory example

    1.1.1 The WHGAITMS File

    A special file called WHGAITMS that describes the Google Analytics data items is required. It is included in your installation, so you should not usually be concerned about this file. If WHGAITMS is not in your Warehouse installation directory, or if you wish to obtain the most recent version, you may download WHGAITMS here. (If you download WHGAITMS, save it with name WHGAITMS with no file extension in your Warehouse installation directory.)

    WHGAITMS lists all dimensions and metrics available from the Google Core Reporting API and maps them to Warehouse names, usually by removing the leading "ga:". WHGAITMS is a comma separated value (CSV) text file, and can viewed using a text editor or Microsoft Excel.

  • 1.2 Java

    Warehouse accesses the Google Analytics API through the use of Java from Oracle, therefore Java must be installed before Google Analytics data can be accessed. If you do not know if Java is installed, it can be difficult to tell for certain.

    In addition, the Google libraries require a Java version of 1.6 or greater. If you already have a Java version installed that is older than 1.6, it is strongly recommended that you upgrade to the latest version using one of the links below.

    1.2.1 Java on Microsoft Windows

    To determine if Java is installed on a Windows system, simply open the Control Panel and look for a control called Java. If Java is there, Java is installed and you can close the control panel. If Java is not there, it needs to be installed. To install Java, go to the Java download page and follow the instructions.

    If this a 64-bit Microsoft Windows OS (most are) and you wish to use DataBridger Studio to access Google Analytics data, you will also need to install 32-bit Java. (Having two Java installations is not a problem.) To check if you need to install 32-bit Java for DataBridger Studio check to see if you have a directory called:
      C:\Program Files (x86)\Java

    If "C:\Program Files (x86)" exists, you are on a 64-bit version of Windows and need "C:\Program Files (x86)\Java" to exist in order  to access Google data with DataBridger Studio. To install 32-bit Java, use this Java download page to download the JRE (Java Runtime Environment) and install the Java Standard Edition  (Java SE) for "Windows x86".

    1.2.2 Java on Unix/Linux

    On Unix/Linux systems, it can be difficult to determine if Java is installed on your system. In addition, once Java is installed, you need to know the installation directory. One way is to follow these steps:
     
     

    1. Open a command terminal/window.
     

    2. Enter the command:

    		 java -version
     
    If this command does not display a Java version, you should download Java from this Java Download page. Then install Java your system. Java SE is the Standard edition, and JRE refers to the Java Runtime Environment. For HP-UX systems, Java is available from Hewlett Packard.

    Once Java is installed and working, we need to find the Java Virtual Machine (JVM) library required by Warehouse. To do this, open a command/terminal window and enter the command:
      java -verbose -version 2>&1 | grep java.lang.Object

    If successful, this command shows where the Java runtime library (rt.jar) is installed. The library needed (libjvm) is nearby. What we need to do is find it. To do this, use the find command on the Java directory looking for libjvm. For example, if the command above showed:
      [Loaded java.lang.Object from /usr/jdk/instances/jdk1.6.0/jre/lib/rt.jar]

    The find command to look for libjvm would be:
      find /usr/jdk/instances/jdk1.6.0 | grep libjvm

    Look for a library file called libjvm.so. If there is more than one, choose one to be used later in the installation.

  • 1.3 Google Analytics Java Libraries

    Warehouse requires the Google Analytics Java client libraries to be on your system to access Google Analytics data. These libraries are distributed with DataBridger and Warehouse in the javalib directory and no action by you is required.

2 Steps to Access Google Analytics

 

The following is a list of steps required to implement Warehouse access to Google Analytics data.


  • 2.1 Checklist of requirements

    To begin, we need to make certain we have everything required. If you are missing anything, see the Requirements section above.  Note that the Java Virtual Machine library name is usually not needed on Microsoft Windows because the Java installation writes the name to the Windows registry.  (If there is an issue on Windows, the library is in a file called jvm.dll, e.g.
    C:\Program Files\Java\jre7\bin\client\jvm.dll)


     

    Item required

    Example

    Java Virtual Machine library (not needed on Windows)

    		 /usr/jdk/instances/jdk1.6.0/jre/lib/i386/libjvm.so
     

    Client ID for Google Analytics

    		 822910492808-bveo5d63lrpiom32opagpnn7f6bda2rs.apps.googleusercontent.com
     

    Client secret for Google Analytics

    		 Ky8Ub4NkdLApJU2IAEKyg4eJ

    Google Analytics View ID

    		 93324637
  • 2.2 Set up wh.ini

    Warehouse finds the Java libraries it needs by looking in the javalib directory. Java .jar files may also be listed in the wh.ini file.  The wh.ini file resides in the Warehouse installation directory. Setup of wh.ini is not typically necessary on Microsoft Windows systems. To edit wh.ini, use a text file editor such as Notepad on Windows or gedit on Linux. The first line of the file must be:

        [Warehouse]

     

    After that, you need another line pointing to your libraries using JVMCLASSPATH like this:

        JVMCLASSPATH=JarFile1;JarFile2;...

     

    On Unix/Linux systems you need another line pointing to your Java Virtual Machine library using JVMLIB:

        JVMLIB=JavaVirtualMachineLibrary

     

    Here is an example wh.ini file from Unix/Linux:


      
    [Warehouse]
JVMCLASSPATH=&
JVMLIB=/usr/jdk/instances/jdk1.6.0/jre/lib/i386/libjvm.so

     

  • 2.3 Running a Test Script

    A simple Warehouse script can be used to verify your Google Analytics setup. The following script displays the number of visits to your website within the last 30 days:


      open g ga user=yourGoogleClientID pass=yourGoogleClientSecret id=yourGoogleViewID
      
    
format gafmt : record
    nv : ga metric visits
end

read gr = g format gafmt for StartDate = &
          ($now - convert(str2date("30","NN"),"interval") pic "YYYY-MM-DD") &
          and EndDate = ($now pic "YYYY-MM-DD")
  print nv
endread

     

    The Google View ID is required to access data, but not to establish a connection to Google. A Warehouse FORMAT statement is required to specify the dimensions and metrics to return. Google Analytics access must always have a start date and end date in YYYY-MM-DD format or Google returns an error.


    2.3.1 Request for Permission

    The first time DataBridger or Warehouse accesses your Google Analytics data, a web browser window is automatically opened that requests access to your data. To allow access click Allow in the browser window. Sebsequent requests will access your data without asking permission.

    Access data is maintained by the Google Analytics libraries in the gastore directory within the Warehouse installation directory. If this directory or files within it are deleted, the permission request is lost and will need to be repeated to access data.

  • 2.4 Setting up DataBridger Studio

    A 32-bit version of Warehouse is shipped with DataBridger Studio. DataBridger Studio version 6.0 supports local Google Analytics data sources. On older 32-but version of Windows, simply follow these instructions using the Warehouse program shipped with DataBridger Studio.

     

    If your DataBridger Studio installation directory is C:\Program Files\Taurus\DataBridger you should be able to put the wh.ini here with no trouble.

     

    However, if your DataBridger Studio installation directory is C:\Program Files (x86)\Taurus\DataBridger (note the x86), you are running on a 64-bit Windows operating system. Since DataBridger Studio is a 32-bit program, you need to have 32-bit Java installed. You can test by checking the directory "C:\Program Files (x86)\Java" If this directory does not exist, you need to install 32-bit Java by following the instructions at Java on Microsoft Windows.


  • 2.5 Setting up the Warehouse Server

    The Warehouse server program resides in the same directory as the Warehouse client program and shares the wh.ini file. Therefore no special setup is required for the Warehouse server. Once the wh.ini file has been setup and the test script runs correctly, the Warehouse server needs only to be stopped and restarted since wh.ini is only read at startup. Once the server is running, you can verify it by using the instructions here: Checking the Warehouse Server.


3 Troubleshooting

 

This section describes ways to diagnose and solve problems. The methods assume access to a command prompt or terminal window so commands can be entered to diagnose problems. After opening the command window, you should then change directory (cd command) to the Warehouse installation directory. Example:

 
  cd C:\Program Files\Taurus\Warehouse

Windows example
  cd /var/taurus/whii/warehouse

Unix/Linux example
 
  • 3.1 Checking Java

    To check if Warehouse can access the Java virtual machine, run Warehouse with the -showinfo parameter which shows a list of diagnostic information. Look near the bottom for an item called Java Virtual Machine. If it says Available, the Java virtual machine is available and you may move to the next step. If it says Unavailable, then either Java is not installed or Warehouse could not find the virtual machine library. If you cannot find "Java Virtual Machine", then look at the first line Program version. Warehouse versions prior to 3.04 cannot access Java, so you will need to upgrade Warehouse. Example:

      wh.exe -showinfo

    Windows example
      ./warehouse -showinfo

    Unix/Linux example

    3.1.1 Checking Java on Microsoft Windows

    If Java is unavailable on Windows, the typical cause is that Java is not installed or that you are running 64-bit Windows, but a 32-bit Warehouse (shipped with DataBridger Studio). To install, see above Java on Microsoft Windows. If you need 32-bit Java on a 64-bit system, the -showinfo above will show:
     
      Java Virtual Machine : Unavailable (Need 32-bit Java)

    If this is the case, see the instructions for installing 32-bit Java above Java on Microsoft Windows. If Java is installed, you may have a more unusual problem and should contact Taurus Software customer support at (650) 482-2022 x200.

    On older Windows operating systems (Windows XP, etc.) you may see a dialog box indicating that the file MSVCR100.dll is missing:

      This application has failed to start because MSVCR100.dll was not found. Re-installing the application may fix this problem.

    If you see this message, do not reinstall anything. Simply go to the Microsoft download site and follow the instructions to download and install MSVCR100.dll.

    If you see a similar message about MFC120U.dll instead, go to this Microsoft download site and follow the instructions to download and install.

    3.1.2 Checking Java on Unix/Linux

    If Java is unavailable on Unix/Linux, it can be difficult to determine the cause. First, make certain Java is installed, then determine the install location and find the libjvm.so file as shown above. Now set the environment variable JVMLIB to the full file name of the libjvm.so file, then export JVMLIB. Then run Warehouse with the -showinfo parameter again. Example:

      JVMLIB=/usr/jdk/instances/jdk1.5.0/jre/lib/i386/libjvm.so
      export JVMLIB
      ./warehouse -showinfo

    If Java is still unavailable, you should contact Taurus Software customer support at (650) 482-2022 x200. If Java is available, the JVMLIB value should been moved to your wh.ini file as shown above.

  • 3.2 Checking the WHGAITMS file

    The file WHGAITMS is required. It is included in your installation, so you should not usually be concerned about this file. Once Java is available, you can test for WHGAITMS by running Warehouse with -c and pressing ENTER at the first prompt. After ENTER, Warehouse checks for WHGAITMS and if it finds it, then prompts for Google login information. If WHGAITMS is not found, Warehouse silently quits. If you need WHGAITMS, you may download WHGAITMS here. (If you download WHGAITMS, save it with name WHGAITMS with no file extension in your Warehouse installation directory.) Example, showing WHGAITMS installed correctly:

    .\wh.exe -c
      Enter name or IP address of server      ->
      Enter Google Analytics login (optional) ->

  • 3.3 Checking the Google Libraries

    Java code is compiled into class files and class files are often grouped in .jar files. Google distributes their libraries as .jar files. Warehouse needs to know where the Google .jar files are so Warehouse can tell the Java Virtual Machine. This is done by adding the .jar file locations to the wh.ini file.  We can test the Google libraries by running Warehouse with -c and entering our Google login information.

    .\wh.exe -c
      Enter name or IP address of server      ->

    Press ENTER here
      Enter Google Analytics login (optional) ->

    Enter Google client ID
      Enter Google password                   ->

    Enter Google client secret
      Enter Google Analytics ID (optional)    ->

    Press ENTER here

    What happens at this point, depends on your setup. If everything is correct, you will see a sample OPEN statement with an encrypted password followed by:
      Connection to Google Analytics SUCCESSFUL.

    If you see an error that looks like the one below, the Google Analytics libraries could not be found. This is usually because your wh.ini file does not point to the Google Analytics .jar files in he JVMCLASSPATH section.  Verify the JVMCLASSPATH section in the wh.ini file.

      Error opening GA connection: Error finding class com/google/gdata/client/analytics/AnalyticsService: java.lang.NoClassDefFoundError: com/google/gdata/client/analytics/AnalyticsService DJERR 8431 (WHERR 19306)
     
      *** Connection to Google Analytics FAILED!.

  • 3.4 Troubleshooting Warehouse Scripts

    Decoding the meaning of error messages from Google can be trying.  Here is a list of some of the more common script errors and what they mean:

    Example 1:

    Error message:

    		 Error getting Google Analytics data: Exception occurred in method get: java.lang .IllegalArgumentException: Parameter ids must conform to the pattern ga:[0-9]+ D JERR 8442

    Cause:

    This error message is caused when attempting to read data without specifying a View ID on the OPEN statement

    Solution:

    Provide a valid View ID on the OPEN statement in your Warehouse script. See Google Analytics View ID.


    Example 2:

    Error message:

    		 Error retrieving Google Analytics data: Exception occurred in method execute: com.google.api.client.googleapis.json.GoogleJsonResponseException: 403 Forbidden { "code" : 403, "errors" : [ { "domain" : "global", "message" : "User does not have sufficient permissions for this ... (WHERR 1 9338) Error in statement 12 (WHERR 8007)

    Cause:

    This error message is caused when attempting to read data with an invalid view ID specified on the OPEN statement. The important part of this message is where it says does not have sufficient permissions, which indicates the the View ID used does not have permission to read the data.

    Solution:

    Provide a valid View ID on the OPEN statement in your Warehouse script. See Google Analytics View ID.


    Example 3:

    Error message:

    		 Start date end end date are both required. (WHERR 19333)

    Cause:

    This error message is caused when attempting to read data without specifying both a start date and an end date. The important part of this message is where it says required.

    Solution:

    Provide both a start date and an end date on the READ statement in your Warehouse script.

    Example 4:

    Error message:

    		 Error getting Google Analytics data: Exception occurred in method get: java.lang .IllegalArgumentException: Parameter endDate must conform to the pattern [0-9]{4 }-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) DJERR 8442

    Cause:

    This error message is caused when the end date is not in YYYY‑MM‑DD format.

    Solution:

    Provide both a start date and an end date on the READ statement that is in YYYY‑MM‑DD format.

  • 3.5 Checking the Warehouse Server

    Since the Warehouse server program resides in the same directory as the Warehouse client program, once the wh.ini file has been setup and the test script runs correctly, the Warehouse server needs only to be stopped and restarted. Run the Warehouse client program with the -serverinfo serverName parameter to show diagnostic information from the server. Example:

      wh.exe -serverinfo myserver

    Windows example
      ./warehouse -serverinfo myserver

    Unix/Linux example

    If -serverinfo fails, either the Warehouse server is not running or you have a network/firewall issue. In this case, please check with your network administrator.

    3.5.1 Checking Java on a Warehouse Server

    Look near the bottom of the -serverinfo output for an item called Java Virtual Machine. If it says Available Warehouse can access Java. If it says Unavailable, then use a window to login to the server and troubleshoot the Warehouse client program.

    • 3.5.2 Checking Google access to a Warehouse Server

    We can test the Google access to a Warehouse Server by running Warehouse with -c and entering our Google login information.

    .\wh.exe -c
      Enter name or IP address of server      ->

    Enter server name
      Enter user name on server (Optional)    ->

    Enter server user name
      Enter password                          ->

    Enter server user password
      Enter remote database type (optional)   ->

    Enter GA
      Enter Google Analytics login (optional) ->

    Enter Google client ID
      Enter Google password                   ->

    Enter Google client secret
      Enter Google Analytics ID (optional)    ->

    Press ENTER here

    If everything is correct, you will see a sample OPEN statement with an encrypted password followed by:
      Connection to Warehouse server myserver SUCCESSFUL.

    If the connection is unsuccessful, use a window to login to the server and troubleshoot the Warehouse client program.

    3.5.3 Checking Google Script access to a Warehouse Server

    A simple Warehouse script can be used to verify Warehouse server access to your Google Analytics data. The following script displays the number of visits to your website within the last 30 days:


      open g remote user=yourServerUser pass=yourServerPassword &
           ga user=yourGoogleClientID pass=yourGoogleClientSecret id=yourGoogleViewID
      
    
format gafmt : record
    nv : ga metric visits
end

read gr = g format gafmt for StartDate = &
          ($now - convert(str2date("30","NN"),"interval") pic "YYYY-MM-DD") &
          and EndDate = ($now pic "YYYY-MM-DD")
  print nv
endread

     

    If your server has been setup correctly and the security informatiom in this script is correct, then this script will complete successfully.

Last updated 10/11/2016