Version 1.

Atoll History Module

User Manual
AD022

Atoll History Module - User Manual

Forsk 2014

Table of Contents

Atoll History Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Installing the Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Enabling the Add-in in Atoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Using the Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

4.1
4.1.1
4.1.2
4.1.2.1
4.1.2.2
4.1.2.3
4.1.2.1
4.1.2.2
4.1.2.5
4.1.3
4.1.3.1
4.1.3.2
4.1.3.3
4.1.4
4.1.4.1
4.1.4.2
4.2
4.2.1
4.2.2

Atoll History Module Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Item Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering by Item Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering by Item Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering by Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering by Item Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering by Item Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Item Explorer Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
History Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
History Grid Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
History Grid Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exporting History Grid Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tree Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Copy/Paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integration with the Atoll Scenario Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Atoll History Module and Virtual Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5
5
6
6
6
6
6
6
6
7
7
7
8
8
9
9
9
9
9

Troubleshooting FAQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

AD022

Atoll History Module - User Manual

1 Atoll History Module

The Atoll History Module (AHM) is developed by Forsk, and is available on demand. It can be used with Atoll version 2.8.3
and above. It can be used to track changes committed by users to the master database project.

Dedicated easy-to-use graphical interface to visualise items history

Support of the following project types:

GSM
UMTS
LTE
Microwave
WiMAX and Wi-Fi
3GPP Multi-RAT (GSM/UMTS/LTE)
3GPP2 Multi-RAT (CDMA/LTE)
GSM

UMTS

LTE

Sites
Transmitters
TRGs (subcells)
TRXs
Secondary Antennas
Repeaters / Remote Antennas
Neighbours
External Neighbours

Sites
Transmitters
Cells
Secondary Antennas
Repeaters / Remote Antennas
Neighbours
External Neighbours

Sites
Transmitters
Cells
Secondary Antennas
Repeaters / Remote Antennas
Neighbours
External Neighbours

3GPP

3GPP2

Sites
GSM / UMTS / LTE Transmitters
GSM TRGS (subcells)
GSM TRXS
UMTS / LTE Cells
GSM / UMTS / LTE Secondary Antennas
GSM / UMTS / LTE Repeaters - Remote Antennas
GSM / UMTS / LTE Neighbours
GSM <-> UMTS Neighbours
GSM <-> LTE Neighbours
UMTS <-> LTE Neighbours

Sites
CDMA / UMTS Transmitters
CDMA / LTE Cells
CDMA / LTE Secondary Antennas
CDMA / LTE Repeaters - Remote Antennas
CDMA / LTE Neighbours
CDMA <-> LTE Neighbours

WiMAX / Wi-Fi

Microwave

Sites
Transmitters
Cells
Secondary Antennas (WiMAX only)
Neighbours
External Neighbours

Sites
Hubs
Links
Point-Multipoint
Multihops
Multihops Links

Filtering capabilities based on:

Radio items or item types
Item status (New, Modified, Deleted)
Modification date
User(s) who made the modifications

History grid display capabilities based on:

Rounding of decimal values

Multi-format export capabilities:

Tab-delimited text file
Excel

Persistent user preferences saved in Windows registry

Atoll History Module - User Manual

Forsk 2014

2 Installing the Add-in

You can install the add-in separately from Atoll using the add-ins setup program.
The setup program of the Atoll History Module is supplied in both:

a 32-bit version for Atoll 32-bit: "AtollHistoryModule_<version>.exe", and

a 64-bit version for Atoll 64-bit: "AtollHistoryModule_x64_<version>.exe"

Before installing the 64-bit version of this add-in, make sure that Atoll 64-bit is installed
correctly. For more information, see the Atoll Administrator Manual.
Installing the Add-in
To install the add-in:
1. Run the add-in setup program.
2. Select an installation folder for the add-in. By default, the installer uses the Add-ins directory in the installation
directory of Atoll.
3. Click Next. The add-in is installed.
4. Once the installation is complete, click Finish to exit the setup.
5. Restart Atoll.
Uninstalling the Add-in
To uninstall the add-in:
1. Exit Atoll.
2. Run the add-ins uninstall program located in the add-ins installation folder, or uninstall the add-in through the
Windows Control Panel. In both cases, a confirmation box appears.
3. Click Yes to confirm. An information dialog appears informing you that the add-in was successfully removed.
All components are removed except the add-in initialisation file which can be retrieved
during a future installation in the same directory.

3 Enabling the Add-in in Atoll

Once installed, the add-in is available in the list of add-ins installed with Atoll.
To enable the add-in in Atoll:
1. Select Tools > Add-ins and Macros from the menu bar. The Add-ins and Macros dialog box appears.

Figure 1: The Add-ins and Macros dialog box

2. Select the Atoll History Module check box.
3. Click Close. The Atoll History Module add-in button (
Module command appears in the Tools menu.

) is displayed in the Add-in toolbar and the Atoll History

AD022

Atoll History Module - User Manual

You can verify the installation details of the add-in by clicking the Details button
in the Add-ins and Macros dialog box.
If you disable the add-in, the Atoll History Module add-in icon ( ) is removed
from the Add-in toolbar and the Atoll History Module command is greyed in the
Tools menu.

4 Using the Add-in

4.1 Atoll History Module Interface
When clicking on the Atoll History Module icon or the entry in the Tools menu, the dedicated interface appears.

Figure 2: Atoll History Module - Main Window

If an item monitored by the Atoll History Module (Site, Transmitter, Repeater, etc.) is selected in Atoll before opening the
Atoll History Module interface, history information will be focused on this item. If no item (or a non-monitored item) is
selected, the history interface will show the history details of all items, based on the default filters.

4.1.1 Item Explorer

The item explorer window, located on the left hand side of the interface, is a tree-based display of all the items monitored by
the Atoll History Module matching the current filtering criteria.

Figure 3: Atoll History Module - Item Explorer

Atoll History Module - User Manual

Forsk 2014

By clicking on the elements of the tree, the user can get history details of the selected item.
It is also possible to double-click on an item to reset the view and focus on that specific item, or group of items:

Item: When double-clicking an item the tree is rebuilt, starting from the Site the item belongs to
Item Folder: When double-clicking a folder, the tree is rebuilt with the data of that folder only. Double-clicking a folder
is equivalent to selecting a specific item type in the filters section.

4.1.2 Filters
The filter section of the Atoll History Module interface contains the different options available to filter the data in the Item
explorer.

Figure 4: Atoll History Module - Filters

4.1.2.1

Filtering by Item Type

The item filtering dropdown menu allows the user to select a specific item type group to focus on. The item types depend on
the radio technology of the project.

4.1.2.2

Filtering by Item Status

Filtering by Item Status allows the user to include or exclude items with a specific status:

4.1.2.3

New: Item has been created but never modified

Modified: Item has been modified at least once
Deleted: Item has been deleted

Filtering by Date
Filtering by Date allows the user to select a date range to review item changes. Several date filtering options are available:

4.1.2.4

Last 7 Days: Only items which have been created/modified/deleted during the last seven days are listed
Last 31 Days: Only items which have been created/modified/deleted during the last 31 days are listed
Last 365 Days: Only items which have been created/modified/deleted during the last 365 days are listed
Custom: The custom date filter option opens a calendar-like interface which allows the user to select a specific date
range. Only items which have been created/modified/deleted within this range are listed
Since Last Synchronization: When selecting this option, the history module will list all items which have been modified
in the database but not yet in the user's project.
All: No date filtering

Filtering by User(s)
Filtering by User allows you to limit the list of displayed items to those created/modified/deleted by a specific user, or by a
group of selected users.
This filter displays user logins as defined in the database.

Figure 5: Atoll History Module - Filtering by User(s)

4.1.2.5

Updating the Item Explorer Content

When the user modifies one or several filters, he must click the Update button to update thecontent of the Item Explorer.

AD022

Atoll History Module - User Manual

Figure 6: Atoll History Module - Update Progress Window

4.1.3 History Grid

The history grid is a dynamically-built table which contains the history of the item currently selected in the Item Explorer
window.

Figure 7: Atoll History Module - History Grid

4.1.3.1

History Grid Content

The history grid contains the list of records for a specific item. Every time an item is created, modified or deleted, a new record
is created. This record contains the properties of the item after the change.
When two or more records are available, the Atoll History Module computes the differences between each record and the
previous one. When a difference is found, the changed field is highlighted.
Records are stored by date; the most recent change is always on top.

4.1.3.2

History Grid Settings

The grid settings section contains options to modify the display of the History Grid.

Figure 8: History Grid Settings

Hide non-modified-columns
The hide non-modified columns option allows the user to change the display of the History Grid by only showing fields for
which at least one change has been found in between all the records.
Round decimal values
By default, the floating point values in the Atoll History Module are displayed with an unlimited number of digits after the
decimal point. If you want, you can set the display precision in the history grid by adding the following lines in the Atoll.ini file:
[Grids]
NbDecimals = N #where N = number of digits after the decimal point
The next time you launch Atoll, select the Round decimal values check box to take the new floating point value into account.
Conversely, clear the the Round decimal values check box to return to the default floating point value (maximum precision).

Figure 9: Atoll History Module - History Grid with Rounded Decimal Values (NbDecimals = 4 in Atoll.ini)

Atoll History Module - User Manual

4.1.3.3

Forsk 2014

Exporting History Grid Content

It is possible to export the content of the History Grid by copy-pasting a selection of cells.
Selection Options
Selection is possible using the mouse and / or keyboard. Non-contiguous cell selection is available by pressing the Control key
while selecting different sets of cells.

Figure 10: History Grid - Non-contiguous Selection

To select the entire table, the user can click the # sign, on the upper left-hand corner of the grid (the Ctrl+A keyboard shortcut
is also available).
Column Headers
Column headers can be automatically included when copying a set of cells. Two options are available:

Only when copying the whole table: Headers will be automatically added only when the user selects the entire grid.
Always: The column headers will always be automatically added.

Those options are available from the Options menu of the add-in. For more details, see "Options" on page 8.
Export Format
Two export formats are currently available. Those formats are automatically managed by the add-in and the best one will be
used based on the application the selection is pasted to:

Tab-delimited plain text: This format is automatically selected when exporting the data to a simple text application
(e.g. Notepad, WordPad). This format does not preserve the grid display properties.

Figure 11: Plain Text Export

HTML: This format is automatically selected when exporting the data to an application which supports HTML format
(e.g. Excel, Word). The HTML format preserves the display properties of the grid.

Figure 12: HTML Export

4.1.4 Options
The options button in the Atoll History Module interface opens the list of available parameters for the add-in. Options are
saved separately for each individual user in the Windows registry.

AD022

Atoll History Module - User Manual

Figure 13: Atoll History Module: Options

4.1.4.1

Tree Filters
This filters options allow the user to choose the default filters to be used when opening the Atoll History Module window.

4.1.4.2

Copy/Paste
The copy-paste options allow the user to choose when to automatically include column headers, when exporting Grid data to
an external application.

4.2 Integration with the Atoll Scenario Manager

4.2.1 Description
Starting with version 1.2, the Atoll History Module is compatible with the Atoll Scenario Manager. This means that if a
scenario-based project is used, displayed history information will follow the same rule as defined in the scenario.
Custom field-based filtering as well as polygon-defined boundaries are automatically taken into account, thus reducing the
amount of data displayed in the Atoll History Module window, and improving both performance and visibility.

4.2.2 Atoll History Module and Virtual Projects

The Atoll Scenario Manager relies on automatic management of virtual projects, at the database level. When a database
operation is performed (opening a project, archiving, refreshing,) the database virtual project is automatically adjusted to
take into account the parameters of the selected scenario.
When opening the Atoll History Module window, the virtual project must correspond to the active document in Atoll. If that
is not the case, an information message is displayed, indicating that the active document must be refreshed in order for the
virtual project to be rebuilt based on the active document.

Atoll History Module - User Manual

Forsk 2014

5 Troubleshooting FAQ
When I click on the add-ins icon, I get an error message saying that the add-in requires "a more recent version of Atoll".
The Atoll History Module can only work with Atoll 2.6.2 or later.
When I click on the add-ins icon, I get a "Not Connect to ORACLE" error message.
Check that your computer is properly connected to the network, and that the database the Atoll project is connected
to is available.
When I click on the add-ins icon, I get a "This document is not connected to a database" error message.
The project you are working on is not linked to a database. History data is only available for connected projects.
When I click on the add-ins icon, I get a "Table or View does not exist" error message.
The database project has not been properly upgraded to be compatible with the Atoll History Module.
The add-in seems to work, but the Item Explorer window remains empty.
Check the date filters; there might not have been any recent change on the selected item(s).

10

AD022

Atoll History Module - User Manual

11

 Head Office
7 rue des Briquetiers
31700 Blagnac, France
Tel: +33 562 747 210
Fax: +33 562 747 211

AD022

US Office

China Office

200 South Wacker Drive Suite 3100

Chicago, IL 60606, USA
Tel: +1 312 674 4800
Fax: +1 312 674 4847

Suite 302, 3/F, West Tower, Jiadu Commercial Building,

No. 66 Jianzhong Road, Tianhe Hi-Tech Industrial Zone,
Guangzhou, 510665, P. R. of China
Tel: +86 20 8553 8938 Fax: +86 20 8553 8285

www.forsk.com

September 2014