Installing the Explore Analytics Agent
Contents
Introduction
The purpose of the Explore Analytics Agent is to provide data access to databases that reside in your private network and cannot be accessed directly from the outside. This page describes the process of installing an agent on a Windows computer. When the installation is completed, you can proceed to create a data source using the newly installed agent.
Before You Begin the Installation
Select a computer to install the agent on. This can be any Windows computer for which you have local administrator access. Ideally, you'd want to select a computer that's always running and is physically secure, although for testing purposes you can certainly install the agent on your laptop computer, for example. The computer that you select must have connectivity to your database. In other words, you should test that you can connect to your database from your computer.
A single CPU computer with 1GB of available disk space and 1GB of available memory should be enough for running the agent. By "available" space or memory we mean that it's not used by the operating system or another application and is available for the agent.
Installation
Note: if you need to the agent for a Microsoft Access data source, you need to install the 2018 version of the agent. Please read the note Installing the 2018 version of agent before proceeding.
To begin, select the option "Install an Explore Analytics Agent" from the "Data" menu.
This multiple-step dialog guides you through installing, configuring and testing the agent.
Installation
Use the link to download the file "agent_installer.msi" to your computer and then use this file to install the agent on the computer that you have selected. Please note that you may see warnings from your anti-virus software because it is not familiar with this file and because the file is executable. In such case you'll need to select the option to save (keep) the file anyway.
Once you have the "agent_installer.msi" file on the selected Windows computer, run it by double-clicking it in Windows file explorer.
If you have an older version of the Explore Analytics Agent on that computer, you'll need to uninstall it using the Control Panel "Programs and Features".
The installation will prompt for a folder location. We highly recommend keeping the default location.
The installation will create a Windows Service. This is a program that runs in the background and has no user interface. When the installation is complete, go to the next step, "Confirmation".
Confirmation
Let's check that the Explore Analytics Agent is installed properly and its running. To do that, you'll use the Windows Control Panel. Go to "Administrative Tools" and select "Services". Find the "Explore Analytics Agent" and see that its status is "Started". If it is, then we're good to go to the next step.
Notes: The agent writes a log file which may be useful for troubleshooting. You can find this log file in the folder where you installed the Explore Analytics Agent. By default this folder is:
C:\Program Files (x86)\Explore Analytics\Explore Analytics Agent
The name of the log file is "agent.log".
Configuration
If all is well, then our next step is to give the agent its configuration file, "agent.properties". Without this file, the agent is not doing much but checking for this file every 30 seconds. The location of the file is the installation folder described in the previous step (the folder where the log file resides). In this step you'll download the agent.properties file from Explore Analytics and place it in the installation folder. Windows will ask you (as the administrator) to authorize placing this file in the installation folder -- go ahead and give that permission.
The configuration file has encrypted entries. The agent will decrypt these entries and use them to connect to Explore Analytics using a service account that's created for you. You can see this service account when you display a list of users using the "Users" option on the "Admin" menu. You'll see a user named "agent_" followed by some digits. This account is only used by the agent to connect to your account and service requests for data for its configures data sources.
Test
In this step, we'll check that the agent had read its configuration, connected to Explore Analytics, and is ready to service requests for data.
When you click the "Test" button, a request is queued for the agent. If working properly, the agent will immediately answer the request. Otherwise, you'll wait a moment and then be told that the request timed out waiting for the agent.
Restarting the Explore Analytics Agent
If you determine that the agent needs to be restarted (assuming it's install on a Windows OS), you can either restart your computer, or:
- Use the Windows Control Panel. Go to "Administrative Tools" and select "Services"
- Using "Services" locate and select the "Explore Analytics Agent" and using the VCR buttons on the toolbar "Restart service", or "Stop" and then "Start"
Upgrading the Explore Analytics Agent
To upgrade the agent, follow these steps:
- Using the Control Panel "Programs and Features", select "Explore Analytics Agent" and uninstall it
- Download the new agent_installer.msi file using the first steps in the Installation section above
- Install the Explore Analytics Agent into the same folder where it was previously installed. The agent properties file is there from the previous installation.
Moving the Agent to another Computer
To move the agent to a new computer follow these steps:
- Uninstall the agent from the old computer using Control Panel "Programs and Features" Add/Remove Program. Don’t worry, the configuration is left undeleted.
- Install the agent on the new computer using the first step of the agent installation instructions in the section Installation. No need to perform the configuration steps, we’ll copy it from the old computer.
- After you installed on the new computer, the agent is running but is waiting for its configuration. Copy the file "agent.properties" from the old computer to the agent folder on the new computer. You’ll need admin privilege to put the file in the agent folder on the new computer.
Within a minute of placing the properties file, the agent should connect.
Getting Help
Setting up an agent-based data source is the most difficult task in Explore Analytics. Don't hesitate to seek help. You can contact Explore Analytics Support.
