Introduction - The Directive Line

Introduction - The 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 RemoteAccess 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 in the Developer Guide.

The first line, known as the directive line, is formatted as in this example:

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

Each of the elements below is separated by a tab:

 

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)

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

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 need only supply 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.

InterMapper also tries to handle incorrect data. The import process protects against and recovers sensibly from faulty, ill-formatted, or inconsistent input values. Certain data (invalid format for an IP address, for example) cannot succeed, and will be reported as an error. Most other data should be 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 a success or error indication.

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.

Notes:

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]