Advanced Data Importing

Introduction - Directive Line

If you need more control over the import process, you can use the Directive line technique instead of a spreadsheet-style import file. In addition to inserting new devices, you can update specific attributes of existing devices, change their appearance or location, and delete them.

NOTE: You can automate the importing of map data by sending commands to Intermapper Remote Access through its command-line interface. This allows you to interact with Intermapper through your own scripts. For more information, see Using the Command Line Interface.

The first line, known as the directive line, is formatted as follows:

# format=tab table=devices fields=id,name,address modify=address match=id

Each of the following elements are separated by a tab:

  • The first line must begin with pound sign (#).

  • The table=devices parameter specifies which table the data should be imported into.

    Valid choices are detailed in Data types.

  • You can generate a list of fields and descriptions for any data type by exporting the Schema table. For more information, see Exporting Data From Maps.
  • You can include columns in your import file from both the Device and Vertices tables. Intermapper automatically applies the Vertex attributes appropriately to the vertex linked to the indicated device.
  • The fields=id,name,address parameter identifies the order of the data in the columns. In this example, there are three columns for the device's ID, name, and address.
  • The modify and matchparameters combine to specify which device attributes to change, and which device attributes to use to verify that the correct device has been found.
Directive Parameter Format/Options

Format

Supported file formats:

  • tab - tab-delimited
  • csv - comma-separated
  • xml - XML format (see an exported file for the format)

Example: 

format=tab

Table

Available values for the table directive are listed in Data types, below.

Examples:

table=devices
table=vertices

Modify

Comma-separated list of field names. Use this parameter to specify which of the columns you want to update. You can combine this with the optional Match parameter.

Note: If there is no Match parameter, the ID field is used to find matches. If no IDfield exists, the import fails.

Example:

modify=ID,MapName,Address,Latitude,Longitude

Match

Comma-separated list of field names. Use this parameter to specify which of the columns you want to use to determine whether to modify device values.

If no Match parameter is included, the ID field is used to find matches.

If no ID field is included in the file, the import fails.

Example: 

match=MapName,Address

Insert

Comma-separated list of field names. Use this parameter to specify the fields you want to set when creating the device.

You must include a combination of at least two fields whose Access attribute is "CREATE" (MapPath, Address, DNSName, IMProbe, MapID). To see the valid combinations, see Device Attributes. When no valid MapPath is included, one is created for you, named "Untitled 1".

Once the device is created using one or more of these fields, Intermapper attempts to set the values of the remaining fields specified in the Insert parameter to the values in the corresponding columns.

Insert fields are evaluated from left to right. If, for example, you specify an Address, DNSName, and IMProbe in that order, the Address is set, and the DNSName is resolved to it, and remaining fields are set from the IMProbe parameter.

Examples: 

Insert=MapPath,Address,Name,Latitude,Longitude

 (The example above creates devices in the specified maps with the specified addresses, names, latitude, and longitude.)

Delete

Comma-separated list of field names. Use this parameter to specify which of the columns you want to use to determine whether a device should be deleted.

Example:

delete=MapName,Probe

(The example above would delete all devices in the specified maps that use the specified probes)
Group

Comma-separated list of field names.

Behaves exactly like the Insert directive, except when it encounters a device to be inserted as a probe group. Devices immediately following the probe group with the same address (and not a probe group) are added to the group.

When another probe group is encountered, the previous group is ended, and subsequent entries are added to the new group.

Note: If the Intermapper server cannot resolve the DNS name, a probe group is added by IP address. This may prevent subsequent entries from being added to the probe group.

Examples:

group=MapName,MapPath,Address,Name,Latitude,Longitude

Remaining Lines - Specifying the Data

The remaining lines of the file contain the data as specified in the fields definition described above. Each column is separated by a tab, and columns must appear in the order specified in the fields definition (for directive line imports) or must correspond to the field names specified in the first line of the file (spreadsheet-style imports).

Available values for the table directive are listed in Data types, below.

Import File Example

Below is an example of an Import file. This file specifies itself as a tab-delimited file containing a list of devices. All devices are going into the map named "MapA", and each device definition contains Address, Probe, Latitude, and Longitude columns.

# format=tab table=devices fields=MapName,Address,Probe,Latitude,Longitude 
MapA 192.168.2.100 http 43.3 -72.0
MapA 192.168.2.101 http 43.9 -72.3
MapA 192.168.2.102 http 43.8 -72.8
MapA 192.168.2.103 http 43.0 -72.4
MapA 192.168.2.104 http 43.2 -72.3
MapA 192.168.2.105 http 43.6 -72.2
NOTE:

The example above creates the devices and assigns probes, but does not set the parameters for the probes. The most efficient way to do this is using the IMProbe URL. It lets you specify the SNMP community string, the probe by file name, and any parameters needed.

Creating Probe Groups

Use the group directive to create a device and add probes to it as a group. The following example adds six devices, with the last one having a probe group. Groups are created in order - probes are added to the group until the IP address changes.

NOTE:

Like the example above, this one creates the devices and assigns probes, but does not set the parameters for the probes. The most efficient way to create and configure a probe group is to use the IMProbe URL. It lets you specify the SNMP community string, the probe by file name, and any parameters needed.

# format=tab table=devices fields=MapName,Address,Probe,Latitude,Longitude
group=MapName,Address,Probe,Latitude,Longitude 
MapA 192.168.2.100 http 43.3 -72.0
MapA 192.168.2.101 http 43.9 -72.3
MapA 192.168.2.102 http 43.8 -72.8
MapA 192.168.2.103 http 43.0 -72.4
MapA 192.168.2.104 http 43.2 -72.3
MapA 192.168.2.105 group 43.6 -72.2
MapA 192.168.2.105 http 43.6 -72.2
MapA 192.168.2.105 snmp 43.6 -72.2

Automatic Placement of Devices

If your map contains no benchmarks (as described in Using Geographic Coordinates) latitude and longitude fields are ignored. You can place devices at specific locations using the XCoordinate and YCoordinate fields (described in the Vertex Attributes). X and Y coordinates are calculated from the upper left.

If the map contains benchmarks to specify geographic coordinates, Intermapper uses them to place devices at the proper location in the map.

NOTE:

In order for Intermapper to place devices accurately using geographic coordinates, two benchmarks must be specified before you import or update the devices. If you have imported the devices to the map before specifying the benchmarks, you can create an export file containing the MapPath, ID, Latitude and Longitude, then re-import the file after specifying your benchmarks. The devices are moved to the appropriate locations on the map.

How Intermapper Inserts Devices

Intermapper places new devices in horizontal rows across the top of the specified map. If either X/Y coordinates or geographic coordinates are specified for the device, Intermapper places it at the specified location on the map.

How Intermapper Handles Errors and Defaults

Intermapper strives to use sensible defaults. The import file needs only a server name, map path, and either an IP address or DNS Name for a new device. Intermapper uses its default settings for other values and parameters.

Note: If the Intermapper server cannot resolve the DNS name , the device is added by IP address.

The import process recovers sensibly from faulty, ill-formatted, or inconsistent input values. An invalid format for an IP address, for example, cannot succeed, and is reported as an error. Most other data is passed along so the device can be added to the map with appropriate defaults. The Intermapper Event Log file contains a line for each newly added device, along with indication of success or error.

If the attribute name in the header of the imported file is not recognized as a valid attribute, Intermapper displays an error message and ignores the contents of that column.

When the import is finished, a summary is written to the Event Log file.

NOTE:
  • Every Intermapper server maintains a unique identifier (the "id") for each of its devices on each map. This makes it a convenient value for matching updated information to an existing device.
  • Intermapper defines a new IMProbe URL that completely specifies all the parameters of an Intermapper Probe. This IMProbe: URL is defined in The IMProbe URL.

Data Types

For each table for which data can be imported or exported, a data type is defined. For information on the different data types, and what information is readable, writable, or both, see the Attributes topic for each data type as linked below. 

table=[data type]
  • devices - imports data specific to devices. See the Device Attributes table.
  • vertices - You can also control other aspects of a device in a map, such as the device's color, label, shape, or font. The vertices type imports data specific to the appearance of devices. See the Vertex Attributes table.
  • interfaces - imports data specific to the switch and router interfaces. See the Interface Attributes table.
  • maps - imports data specific to maps. See the Map Attributes table.
  • notifiers - imports data to describe notifiers. See the Notifier Attributes table.
  • notifierrules - imports data to describe how a notifier is applied. See the Notifier Rules Attributes table.
  • users - imports user account information. See the User Attributes table.
  • retentionpolicies- imports user account information. See the Retention Policy Attributes table