CSV import guide

This guide explains how to import objects from a CSV file into NConf. CSV stands for “comma-separated values”, a file containing tabular data, which is separated by commas or semicolons. Data is typically first edited as a spreadsheet in Excel and then exported to CSV format.

NConf comes with two different CSV import scripts in the 'nconf/bin/' directory:

• add_items_from_csv.pl lets you freely define the contents of your CSV file and imports any type of items
• add_items_from_special_csv.pl dictates a specific CSV file structure and only imports hosts & services

Both scripts will process your CSV input file and create new items in NConf accordingly. Please note that you can only import one type of item at once, e.g. you cannot import hosts and contacts at the same time. That would require two different CSV files (the second script does let you import hosts & services at once). The order of the attributes in your input file is irrelevant.

Say for example you were trying to import contacts from a CSV file. The add_items_from_csv.pl script lets you define the structure of your CSV file as you like. The only restriction is that your CSV file must contain all attributes that are mandatory for that object type in NConf.

The mandatory attributes for 'contact' items in NConf are:

• contact_name
• alias
• email

If you're working with a spreadsheet tool, your sheet would look somewhat like this:

After exporting your spreadsheet to CSV format, or if you're working with a text editor, the data would look somewhat like this:

John Smith;smith;24x7;j.smith@nconf.org;+41757077070
Peter Brown;brown;none;p.brown@nconf.org;+41769876543
James Jones;jones;workhours;j.jones@nconf.org;+41773216585

As you can see, all three mandatory attributes and more are available, assuming “alias” is the real name and “contact_name” is the user id.

Next, we need to define the syntax of the CSV file, so that the import script knows how to map the data. This is done by editing the add_items_from_csv.pl script (make a backup copy first).

Open the script with a text editor. On one of the first lines you will find a set of commands looking like this:

push(@csv_syntax, ...

This is where we tell the import script how the structure of the CSV file looks. The idea is to tell the script which column (from left to right) corresponds to what attribute in NConf. Uncomment or remove any “push” commands that you do not need.

For the example above, the necessary syntax would look like this:

push(@csv_syntax, 'alias');
push(@csv_syntax, 'contact_name');
push(@csv_syntax, 'host_notification_period');
push(@csv_syntax, 'email');
push(@csv_syntax, 'pager');

Make sure you use the exact attribute names as they would appear in a Nagios configuration file. The order of the “push” commands must correspond exactly to the order of the CSV file (from left to right).

Once you've defined the syntax, you can execute the import script. This is how the script is used:

Usage:
./add_items_from_csv.pl -c class -n naming-attr -f /path/to/file [-x (1-5)] [-s]

Help:

  required
  -c  Specify the class of items that you wish to import. Must correspond to an NConf class
      (e.g. "host", "service, "hostgroup", "checkcommand", "contact", "timeperiod"...)
  -n  Specify the naming attribute for the class to be imported. Must correspond with the
      naming attr in NConf (e.g. host: "host_name", service: "service_description"...)
  -f  The path to the file which is to be imported. CAUTION: Make sure you have
      only items of one class in the same file (e.g. "hosts", "services"...)
      Also make sure you import host- or service-templates separately ("host" or
      "service" items containing a "name" attribute)

  optional
  -x  Set a custom loglevel (1 = lowest, 5 = most verbose)
  -s  Simulate only. Do not make any actual modifications to the database.

To import our contacts, we would execute the script like this:

$> cd /path/to/nconf/bin/
$> ./add_items_from_csv.pl -c contact -n contact_name -f /path/to/import.csv

This should give us the following output:

[ Initializing NConf perl-API (library version 0.2, written by A. Gargiulo) ]
[ Copyright (c) 2006-2009 Sunrise Communications AG, Zurich, Switzerland    ]

[INFO]  Started executing ./add_items_from_csv.pl
[INFO]  Adding contact 'smith'
[INFO]  Successfully added contact 'smith'
[INFO]  Adding contact 'brown'
[INFO]  Successfully added contact 'brown'
[INFO]  Adding contact 'jones'
[INFO]  Successfully added contact 'jones'
[INFO]  Finished running ./add_items_from_csv.pl

Finally, check your new contact items in NConf to make sure the import was successful and the attributes were mapped correctly.

Chances are you might encounter one or more errors during import. Here are a few known errors:

[WARN]  Could not find attribute '...' belonging to class '...'. Skipping import of this attribute.

This message indicates that your CSV file might contain an attribute that is unknown to NConf. These attributes will be skipped during import.

[WARN]  Mandatory attribute '...' missing for ...
[ERROR] Failed to add ... Aborting

This message indicates that the import script could not find one or more mandatory attributes in your CSV file. This will cause the import process to abort.

If you wish to import hosts & services only, you may use the script add_items_from_special_csv.pl. This script requires your CSV file to have a specific structure. Each host and service must have a fixed amount of attributes. The amount of services you can add per host is not limited.

The CSV file must be made up of two parts: The first 10 columns are reserved for host specific attributes. The 5 subsequent columns are service specific and can be repeated as many times as necessary. Each service must always consist of 5 columns.

The following columns are required (in this order from left to right):

host attributes:

1. host_name
2. alias
3. address
4. os
5. check_period
6. notification_period
7. contact_groups
8. parents
9. host-preset
10. monitored_by

service attributes:

1. service_description
2. check_command
3. check_params
4. check_period
5. notification_period

(this block can be repeated as many times as needed)

If you're working with a spreadsheet tool, the CSV file would look somewhat like this. Attributes can be left empty, as long as they are not considered mandatory by NConf:

Notice the “gray” part. These are the 5 service specific columns. These 5 columns can be repeated, allowing you to add as many services for each host as you like. The amount of services can differ from host to host (leave unneeded columns empty).

Once you are done editing your spreadsheet, export it to CSV format. This is not necessary if you were already editing the file with a text editor. Your data should look somewhat like this:

switch001;switch001;10.12.8.1;Switch;24x7;24x7;admins;;generic-switch;Default Nagios;check_snmp;check_snmp;!;24x7;24x7
localhost;localhost.nconf.org;127.0.0.1;Linux;24x7;workhours;admins;switch001;linux-server;Default Nagios;check_http;check_http;!;24x7;workhours
dc01;dc01.nconf.org;10.10.1.1;Windows;24x7;workhours;admins;switch001;windows-server;Default Nagios;check_nt;check_nt;!;24x7;workhours

You are now ready to run the import script. This is how the script is used:

Usage:
./add_items_from_special_csv.pl -f /path/to/file [-x (1-5)] [-s]

Help:

  required
  -f  The path to the CSV file which is to be imported.

  optional
  -x  Set a custom loglevel (1 = lowest, 5 = most verbose)
  -s  Simulate only. Do not make any actual modifications to the database.

Executing the script with the above data should give the following output:

$> ./add_items_from_special_csv.pl -f /path/to/special_import.csv

[ Initializing NConf perl-API (library version 0.2, written by A. Gargiulo) ]
[ Copyright (c) 2006-2009 Sunrise Communications AG, Zurich, Switzerland    ]

[INFO]  Started executing ./add_items_from_special_csv.pl
[INFO]  Adding host 'switch001'
[WARN]  Mandatory attribute 'host_is_collector' missing for host 'switch001'. Using default value: 'no'.
[INFO]  Successfully added host 'switch001'
[INFO]  Adding service 'switch001;;check_snmp'
[INFO]  Successfully added service 'switch001;;check_snmp'
[INFO]  Adding host 'localhost'
[WARN]  Mandatory attribute 'host_is_collector' missing for host 'localhost'. Using default value: 'no'.
[INFO]  Successfully added host 'localhost'
[INFO]  Adding service 'localhost;;check_http'
[INFO]  Successfully added service 'localhost;;check_http'
[INFO]  Adding host 'dc01'
[WARN]  Mandatory attribute 'host_is_collector' missing for host 'dc01'. Using default value: 'no'.
[WARN]  Could not link host with os 'Windows' (attr 'os'). No such item.
[INFO]  Successfully added host 'dc01'
[INFO]  Adding service 'dc01;;check_nt'
[INFO]  Successfully added service 'dc01;;check_nt'
[INFO]  Finished running ./add_items_from_special_csv.pl

As you can see, the import script will inform you about any missing attributes and any values it couldn't map. If you omit any mandatory NConf attributes, the import process will terminate with an ERROR. It's therefore recommended to run the import in simulation mode (-s) prior to doing the actual import.

[WARN]  Mandatory attribute '...' missing for ...
[ERROR] Failed to add host ... Aborting

Finally, check your new host and service items in NConf to make sure the import was successful and the attributes were mapped correctly.