Overview
The following Quick Start tutorial is the best place to start if you are new to Attivio. This tutorial walks you through downloading and installing Attivio and creating your first Attivio project, Factbook. In this tutorial, you will:
- Create a new Attivio project and use the Attivio CLI (Command-Line Interface) to start it
- Ingest sample structured and unstructured data using Attivio's connectors
- Retrieve ingested data by executing simple and advanced queries using Attivio's built-in Search UI
Watch This Tutorial
1. Download Attivio Platform
For the purposes of this tutorial, we will assume you are installing the latest version of Attivio Platform 5.6 (which includes Search UI) using a 64-bit Windows operating system with a minimum of 8GB of RAM. For a full understanding of the resources needed for development and production environments, see our System Requirements page.
- Download the Attivio Platform Windows 64-bit Server installer package.
Using Linux
You can adapt the tutorial steps below to Linux fairly easily:
- Follow the Linux Installation steps when installing Attivio Platform
- Execute commands in a terminal session instead of in a Command Prompt window
- Change all command and project paths to use Unix slashes (/) instead of Windows backslashes (\)
- Omit
.exe
suffixes on executables
2. Install Attivio Platform
Unzip and run the Attivio Platform installer following the steps below.
Use a ZIP archive program or Windows' built-in ZIP support to decompress the installation package ZIP archive that you downloaded from the Download Attivio Software page. Next, double-click the decompressed Attivio Platform installer executable to begin the installation process. The install4j Wizard dialog box appears.
Windows 10 When installing Attivio Platform on Windows 10, right-click the installer executable and select the Run as administrator context-menu entry instead of double-clicking. The installer must be run as an Administrator in order for installation to complete successfully.
If the screen shows the message "A previous installation has been detected. Do you wish to update that installation?", it indicates that an existing installation of Attivio Platform 5.6.2 or later is present on the host and that the installer will perform an in-place upgrade rather than creating a complete new installation. Go to the Welcome to the Attivio Platform Setup Wizard step in the Windows In-Place Upgrade Steps section, below, and continue from there to complete the upgrade. The Patent Notice screen appears. Click the Next button to continue installation. The License Agreement screen appears. Read the agreement, then select the I accept the agreement radio button and click the Next button to continue installation. If Attivio Platform 5.6.1 is installed on the host, the Attivio 5.6.1 Detected Screen appears. If you wish to back up any elements of the existing installation directory tree, do so, then click the Next button to continue installation. The Attivio Platform License screen appears. Type the path and filename of your Attivio requires a valid license file. To obtain a license file, refer to the Installing AIE page. The JRE Selection screen appears. If you wish to use the OpenJDK 11.0.3 Java Runtime Environment (JRE) bundled with the installer, click the Next button to continue installation. If you prefer to provide your own Java SE 11 JRE, select the User-defined JRE radio button, then click the Browse… button and navigate to select the JAVA_HOME directory for your desired JRE. The installer will display a warning dialogue box if the location entered is not a valid JRE JAVA_HOME directory. Once the directory is specified, click the Next button to continue installation. Changing the JRE After Installation After installation, you can still change the JRE used for Attivio processes by following the steps outlined on the Updating Attivio JREs page. The Select Installation Type screen appears. If you wish to install the Attivio Platform core product plus the default set of external modules, click the Next button to continue installation. If you wish to omit the default external modules and install only the Attivio Platform core product, select the Core radio button and then click the Next button to continue installation. Most of the Attivio documentation assumes that you have selected the Full option, with the core platform and external modules. Some options mentioned in the documentation may be unavailable if you select the Core option and omit the external modules. The Select Destination Directory screen appears. If you wish to install Attivio Platform to the recommended
Do Not Install to Program Files Directory On some versions of Windows, installing Attivio Platform under the The Select Start Menu Folder screen appears. If you want Attivio Platform to create a Start Menu folder with shortcuts, leave the Create a Start Menu folder checkbox enabled (its default setting), specify a folder name or accept the default The Agent Service Installation screen appears. If you wish to run the Attivio Platform Agent as a Windows service, leave the Install Attivio Platform Agent Service checkbox enabled (its default setting), modify the default Port and Data directory field values if desired, then click the Next button to continue installation. If you do not wish to run the Agent as a Windows service, uncheck the Install Attivio Platform Agent Service checkbox, then click the Next button to continue installation. The installer extracts files. Depending on your choices, it may also install external modules, create a Start Menu folder, or install the Attivio Platform Agent as a Windows service.
If you do not have administrator privileges, Attivio will be unable to install the Attivio Platform Agent as a service. If you don't have privileges to run programs as system services, Attivio will display a warning message indicating that the Attivio Platform Agent service could not be started: In either of these cases, you will need to start the Agent manually before starting the Attivio Command-Line Interface (CLI). The Completing the Attivio Platform Setup Wizard screen appears. Click the Finish button to exit the installer.attivio.license
file into the attivio.license file field, or click the Browse… button and navigate to find the file. Once the file's path and filename has been specified, click the Next button to continue installation.C:\attivio\platform
destination directory, click the Next button to continue installation. If you wish to specify a different installation directory path, type that path into the field or click the Browse… button and navigate to select the desired directory, then click the Next button to continue installation.C:\Program Files
directory causes file permission issues which may block required functionality. Install to C:\attivio
or a similar non-Program Files
path to avoid this problem.Attivio Platform
name, and click the Next button to continue installation. If you do not want Attivio Platform to create a Start Menu folder, uncheck the Create a Start Menu folder checkbox and then click the Next button to continue installation.
3. Download and install the latest patch
Patches are released on a regular basis to fix bugs, add enhancements, and add new functionality. It is a best practice to install the latest patch available for your version of Attivio. You can find details on patches on the 5.6 Patch Information page.
4. Create a new Attivio project (Factbook)
An Attivio project is a collection of configuration files in an Attivio application. Projects include the feature, schema, component definition, and workflow definition files that define how to ingest content, process queries, and handle results within an Attivio application. Multiple projects can be created on a single host, running against the same Attivio installation, and those projects can be managed and developed independently.
To create a new project named Factbook, open a Command Prompt window and execute the following command, replacing the <INSTALL_DIR>
placeholder with the path you specified for your Attivio Platform installation (C:\attivio\platform
by default):
<INSTALL_DIR>\bin\createproject.exe --name Factbook -g demo -m factbook -o C:\attivio\projects
This command tells attivio to create a project named Factbook in the C:\attivio\projects
directory; its project directory will be the C:\attivio\projects\Factbook
sub-directory. The new project includes all modules from the demo group, and additionally includes the factbook module which contains the sample connectors and data you'll use to explore Attivio's ingestion and search capabilities below.
5. Start the project using the Attivio CLI
The Attivio CLI (Command Line Interface) is a small-footprint utility that runs in an interactive console window. It enables you to start, stop and monitor multiple servers in an Attivio project, and also provides tools for deploying and updating the project configuration.
To start your new Factbook project, execute the following steps:
Open a Command Prompt window and execute this command to launch the CLI:
<INSTALL_DIR>\bin\aie-cli.exe -p C:\attivio\projects\Factbook
Depending on your Windows security settings, you may need to run the Command Prompt window as an administrator in order to start Attivio properly using the CLI.
The CLI appears, displaying an aie>
prompt and cursor. Status listings for your project's nodes, perfmon server, and stores appear at the bottom of the Command Prompt window.
At the CLI prompt, type start all
and press Enter. This command tells Attivio to start all servers and nodes defined in the project topology; on the first run, it also automatically deploys the project configuration to the Attivio Platform Agent's ZooKeeper service.
If you are prompted by a Windows security alert dialog box such as the one below, allow access to your domain network for the Attivio Platform OpenJDK JRE (Java Runtime Environment).
At the CLI prompt, execute the status
command until you see the project's perfmon server, store, and node all reporting RUNNING
status. All three indicators at the bottom of the Command Prompt window should display UP(1) DOWN(0)
, indicating that one node, one perfmon server, and one store are available.
6. Ingest data using Attivio connectors
Next, you'll run the project's connectors to populate your Attivio project's index with documents. These connector definitions were added to your project when you included the factbook module in the createproject
step above.
In a web browser, navigate to http://localhost:17000/connectoradmin/, enter username aieadmin
and password attivio
when prompted, and click the Log In button to access the Connector Admin UI screen.
The Insights into Your Data pane shows that your project currently has no indexed documents. Below that pane is the connector list, showing the four pre-defined sample connectors from the factbook module. To the right, a detail pane shows settings for the selected connector (a CSV connector named city).
Hold down the Ctrl key and click to select all four entries in the connector list. (They should all be highlighted, as shown below.) Now click the Selected Items
drop-down control and choose the Run Selected command to tell Attivio to run all four connectors.A Confirm Run dialog box appears. Click Run to start the four connectors.
The Status, Processing, and Processed columns in the connector list update. When each connector completes, its Status indicator disappears and its Last Run date is updated. The Insights into Your Data pane reports details on the documents the connector runs fed to the Attivio index. You now have a populated index which you can query.
7. Open Search UI and execute simple queries
Attivio's search tools allow you to easily retrieve indexed documents. Try out search by performing the following steps:
In a web browser, navigate to http://localhost:17000/searchui/ to access the Search UI application.
The starting screen shows the number of documents in your project's index and the number of sources (connectors) for those documents. The search field contains a default *:*
query, which if issued will match all documents in the index. To get specific information, however, you'll issue a more restrictive search query.
In the search field, select and delete the default *:*
query. Type civil war
into the field and click the Go button or press Enter to submit this query.
The query results screen appears.
At the top left, Search UI reports the number of results (documents) your query produced and the time it took. At the top right, you'll find controls that let you view additional details for search results, sort your results, change the relevancy model used for your query, or paginate through your result set.
In the main results pane, the left section displays a set of facets which focus on elements common to your result documents, such as key phrases or dates included in their text.
The central section displays individual documents in a compact view, with their title, table, and a short teaser representing their text. (Clicking the Details > On button at the top will show a full view of the documents' fields and field values.) Note that your civil war
query string is highlighted, along with the individual terms civil
and war
, where it appears in the results.
To the right, entities identified in the document are displayed with color-coded typing; for the sample data, these include dates, people, companies, locations, languages, and key phrases.
Try some other simple queries:
Query | Description |
---|---|
democracy |
Match documents which contain the term "democracy". |
-democracy |
Match documents which do not contain the term "democracy". |
"civil war" |
Match documents which contain the phrase "civil war". This query returns fewer results than your original |
civil OR war |
Match documents which contain either "civil" or "war", or both. The |
title:Pasadena |
Match documents with title field values that contain the term "Pasadena". |
title:"San Francisco" |
Match documents with title field values that contain the phrase "San Francisco". Again, this query will not match "San" in "San Diego" or on its own; it will only match "San" followed by "Francisco". |
8. Execute advanced queries in Search UI
All the searches you've performed so far have used Attivio's Simple Query Language, which is optimized for ease of use. Try out some of the more sophisticated search tools offered by the Advanced Query Language by following these steps:
In Search UI, switch from Simple Query Language to Advanced Query Language by clicking the drop-down arrow by the magnifying-glass icon (just to the right of the search field) and selecting Advanced.
Type AND(civil, war)
into the search field and click the Go button or press Enter to submit the query.
This is the first query you submitted, but expressed in the Advanced Query Language syntax. It returns the same results in either query language.
Try some additional advanced queries:
Query | Description |
---|---|
AND(civil, war, NOT(independence)) |
Match documents which contain both "civil" and "war" but do not contain "independence". |
REGEX("19[0-9]{2}|20[0-9]{2}") |
Match documents which contain years from the 20th and 21st centuries CE. |
title:STARTSWITH(San) |
Match documents with title field values that start with "San". (San Francisco, San Diego, San José, etc.) |
NEAR(signed, treaty, distance=3) |
Match documents which contain "signed" within three words of "treaty", regardless of the order of the two words. |
ONEAR(signed, treaty, distance=3) |
Match documents which contain "signed" within three words of "treaty", but only if "signed" appears before "treaty". |
JOIN(table:country, INNER(table:city, on=country), INNER(table:medal, on=country), INNER(table:news, on=country)) |
Match countries that have at least one city, have won at least one Olympic medal, and that are currently in the news. The primary results are countries, with expandable Child Document displays under each country displaying cities, Olympic medal wins, and news articles. |
JOIN(table:country, INNER(AND(table:medal, gold_i:>10), on=country), OUTER(table:news, on=country)) |
Match countries that won at least ten gold medals at an Olympics, and include news articles about each country if available. |
9. Stop the project
Now that you've seen Attivio's ingestion and search capabilities at work, follow these steps to stop your project.
At the CLI prompt, execute the stop all
command to stop all of your Attivio project's nodes and servers.
Execute the status
command from the CLI prompt until you see the project's perfmon server, store, and node all reporting STOPPED
status. All three indicators at the bottom of the Command Prompt window should display UP(0) DOWN(1)
, indicating that the node, perfmon server, and store are offline.
At the CLI prompt, type quit
and press Enter to exit the CLI and return to the Command Prompt.
You're done with this Quick Start tutorial.
Keep your sample project, as it'll be the basis of a number of additional Quick Start tutorials that focus on specific Attivio Platform features and functionality.