Atoll History Module 1.3

Version 1.3

Atoll History Module User Manual

AD022

Atoll History Module - User Manual Forsk 2014Table of Contents

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

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

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

4 Using the Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54.1 Atoll History Module Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.1.1 Item Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.1.2 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.1.2.1 Filtering by Item Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1.2.2 Filtering by Item Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1.2.3 Filtering by Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1.2.1 Filtering by Item Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1.2.2 Filtering by Item Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.1.2.5 Updating the Item Explorer Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.1.3 History Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.1.3.1 History Grid Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.1.3.2 History Grid Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.1.3.3 Exporting History Grid Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.1.4 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.1.4.1 Tree Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.1.4.2 Copy/Paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.2 Integration with the Atoll Scenario Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2.2 Atoll History Module and Virtual Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5 Troubleshooting FAQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

AD022 Atoll History Module - User Manual1 Atoll History ModuleThe Atoll History Module (AHM) is developed by Forsk, and is available on demand. It can be used with Atoll version 2.8.3and 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)

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

GSM UMTS LTE

SitesTransmitters

TRGs (subcells)TRXs

Secondary AntennasRepeaters / Remote Antennas

NeighboursExternal Neighbours

SitesTransmitters

CellsSecondary Antennas

Repeaters / Remote AntennasNeighbours

External Neighbours

SitesTransmitters

CellsSecondary Antennas

Repeaters / Remote AntennasNeighbours

External Neighbours

3GPP 3GPP2

SitesGSM / UMTS / LTE Transmitters

GSM TRGS (subcells)GSM TRXS

UMTS / LTE CellsGSM / UMTS / LTE Secondary Antennas

GSM / UMTS / LTE Repeaters - Remote AntennasGSM / UMTS / LTE Neighbours

GSM UMTS NeighboursGSM LTE Neighbours

UMTS LTE Neighbours

SitesCDMA / UMTS Transmitters

CDMA / LTE CellsCDMA / LTE Secondary Antennas

CDMA / LTE Repeaters - Remote AntennasCDMA / LTE Neighbours

CDMA LTE Neighbours

WiMAX / Wi-Fi Microwave

SitesTransmitters

CellsSecondary Antennas (WiMAX only)

NeighboursExternal Neighbours

SitesHubsLinks

Point-MultipointMultihops

Multihops Links3

Atoll History Module - User Manual Forsk 20142 Installing the Add-inYou can install the add-in separately from Atoll using the add-ins setup program.

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 installationdirectory 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 theWindows 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.

3 Enabling the Add-in in AtollOnce 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.

2. Select the Atoll History Module check box.

3. Click Close. The Atoll History Module add-in button ( ) is displayed in the Add-in toolbar and the Atoll HistoryModule command appears in the Tools menu.

The setup program of the Atoll History Module is supplied in both:

a 32-bit version for Atoll 32-bit: "AtollHistoryModule_.exe", and a 64-bit version for Atoll 64-bit: "AtollHistoryModule_x64_.exe"

Before installing the 64-bit version of this add-in, make sure that Atoll 64-bit is installedcorrectly. For more information, see the Atoll Administrator Manual.

All components are removed except the add-in initialisation file which can be retrievedduring a future installation in the same directory.

Figure 1: The Add-ins and Macros dialog box4

AD022 Atoll History Module - User Manual4 Using the Add-in

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

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

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

You can verify the installation details of the add-in by clicking the Details buttonin the Add-ins and Macros dialog box.

If you disable the add-in, the Atoll History Module add-in icon ( ) is removedfrom the Add-in toolbar and the Atoll History Module command is greyed in theTools menu.

Figure 2: Atoll History Module - Main Window

Figure 3: Atoll History Module - Item Explorer5

Atoll History Module - User Manual Forsk 2014By 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 FiltersThe filter section of the Atoll History Module interface contains the different options available to filter the data in the Itemexplorer.

4.1.2.1 Filtering by Item TypeThe item filtering dropdown menu allows the user to select a specific item type group to focus on. The item types depend onthe radio technology of the project.

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

New: Item has been created but never modified Modified: Item has been modified at least once Deleted: Item has been deleted

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

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

4.1.2.4 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 agroup of selected users.

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

Figure 4: Atoll History Module - Filters

This filter displays user logins as defined in the database.

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

AD022 Atoll History Module - User Manual4.1.3 History GridThe history grid is a dynamically-built table which contains the history of the item currently selected in the Item Explorerwindow.

4.1.3.1 History Grid ContentThe history grid contains the list of records for a specific item. Every time an item is created, modified or deleted, a new recordis 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 theprevious 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 SettingsThe grid settings section contains options to modify the display of the History Grid.

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 forwhich 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 thedecimal point. If you want, you can set the display precision in the history grid by adding the following lines in the Atoll.ini file:

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 6: Atoll History Module - Update Progress Window

Figure 7: Atoll History Module - History Grid

Figure 8: History Grid Settings

[Grids]NbDecimals = N #where N = number of digits after the decimal point

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

Atoll History Module - User Manual Forsk 20144.1.3.3 Exporting History Grid ContentIt 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 keywhile selecting different sets of cells.

To select the entire table, the user can click the # sign, on the upper left-hand corner of the grid (the Ctrl+A keyboard shortcutis 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 beused 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.

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.

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

Figure 10: History Grid - Non-contiguous Selection

Figure 11: Plain Text Export

Figure 12: HTML Export8

AD022 Atoll History Module - User Manual4.1.4.1 Tree FiltersThis 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/PasteThe copy-paste options allow the user to choose when to automatically include column headers, when exporting Grid data toan external application.

4.2 Integration with the Atoll Scenario Manager

4.2.1 DescriptionStarting with version 1.2, the Atoll History Module is compatible with the Atoll Scenario Manager. This means that if ascenario-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 theamount of data displayed in the Atoll History Module window, and improving both performance and visibility.

4.2.2 Atoll History Module and Virtual ProjectsThe Atoll Scenario Manager relies on automatic management of virtual projects, at the database level. When a databaseoperation is performed (opening a project, archiving, refreshing,) the database virtual project is automatically adjusted totake 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 thatis not the case, an information message is displayed, indicating that the active document must be refreshed in order for thevirtual project to be rebuilt based on the active document.

Figure 13: Atoll History Module: Options9

Atoll History Module - User Manual Forsk 20145 Troubleshooting FAQWhen 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 connectedto 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 Manual11

AD022 www.forsk.com September 2014

Head Office7 rue des Briquetiers31700 Blagnac, FranceTel: +33 562 747 210Fax: +33 562 747 211

US Office200 South Wacker Drive Suite 3100Chicago, IL 60606, USATel: +1 312 674 4800Fax: +1 312 674 4847

China OfficeSuite 302, 3/F, West Tower, Jiadu Commercial Building,No. 66 Jianzhong Road, Tianhe Hi-Tech Industrial Zone,Guangzhou, 510665, P. R. of ChinaTel: +86 20 8553 8938 Fax: +86 20 8553 8285

Table of Contents1 Atoll History Module2 Installing the Add-in3 Enabling the Add-in in Atoll4 Using the Add-in4.1 Atoll History Module Interface4.1.1 Item Explorer4.1.2 Filters4.1.2.1 Filtering by Item Type4.1.2.2 Filtering by Item Status4.1.2.3 Filtering by Date4.1.2.4 Filtering by User(s)4.1.2.5 Updating the Item Explorer Content

4.1.3 History Grid4.1.3.1 History Grid Content4.1.3.2 History Grid Settings4.1.3.3 Exporting History Grid Content

4.1.4 Options4.1.4.1 Tree Filters4.1.4.2 Copy/Paste

4.2 Integration with the Atoll Scenario Manager4.2.1 Description4.2.2 Atoll History Module and Virtual Projects

5 Troubleshooting FAQ