Example 1

To free up rack space for other applications, some hosts have been moved from the 'Campus' data centre to the newly acquired 'Firehouse' data centre. Discovery and Reasoning have handled the IP address and subnet changes but the Host nodes are still linked to the wrong location. Here is the CSV file to process, called firehouse_move.csv:

name,#HostInLocation:HostLocation:LocationOfHost:Location.name
egon,Firehouse
ray,Firehouse
peter,Firehouse

We process the CSV file with the following command line:

$ tw_imp_csv --username=system --password=system --kind=Host firehouse_move.csv

The script reads the file called firehouse_move.csv line by line. It uses the first line to name the columns. The first column is called 'name', which doesn't begin with a '#' character so it is treated as an attribute name. The second column does begin with a '#' character so it is treated as a specification for some relationships.

No explicit key has been specified so the first (and in this case, only) attribute name is taken to be the key.

Now the script reads the second line. The first field, egon, is in the name column which was selected as the key earlier. So the script uses the search service to find a node of kind Host (from the --kind command line option) that has a name attribute equal to egon. It finds exactly one node matching that search. If it had not found that node, it would have been created. If it had found multiple nodes, an error would have been reported and processing would continue with the next line, NO nodes would have been updated.

Having found the node, it updates it using the other fields on the row. Were there any other attribute columns in the the file, the script would have used these to update the node before looking at the relationships.

The file has only one relationship column. The name is #HostInLocation:HostLocation:LocationOfHost:Location.name. The script searches for a Location node with a name attribute equal Firehouse, this row's value for the column. Having found the Location node, the script creates a HostLocation relationship to it with the Host node playing the HostInLocation role and the Location playing the LocationOfHost role.

The script then processes the second and third data rows, updating the ray and peter nodes with the new location.

Example 2

A new host has been installed in the Firehouse data centre. Due to pressure from the organisation's E-services Protection Adviser, there is now a firewall preventing discovery of hosts on that site. Until a remote discovery slave can be installed, the Firehouse sysadmins have been sending us spreadsheets with the changes.

Here is the's a CSV file, called new_host.csv:

name,fqdn,#HostInLocation:HostLocation:LocationOfHost:Location.name,#ITOwnedItem:ITOwner:ITOwner:Person.name,ip_addrs,#HostOnSubnet:HostSubnet:Subnet.name
winston,winston.example.com,Firehouse,"Melnitz,J","['10.3.4.1','192.168.101.45']","['10.0.0.0/8','192.168.101.0/24']"

We process the CSV file with the following command line:

$ tw_imp_csv --username=system --password=system --kind=Host --create new_host.csv

The command line is nearly the same as in Example 1. The differences are that the filename has changed because we are processing a different file and we are using Create Only mode.

As in Example 1, the script searches for Host nodes with a name attribute equal to winston. This time, because it is in create mode, the script checks that there are no matching nodes. If there were, the script would report an error and skip the row.

Now the script creates a new node. It populates the attributes of the node from the non-relationship fields in the data. The ip_addrs field is a list and the value starts with a '[' character so it is converted into a list. The new node has attributes:

• name = 'winston'
• fqdn = 'winston.example.com'
• ip_addrs = [ '10.3.4.1', '192.168.101.45' ]

Then the script adds the relationships. The location relationship column is processed in the same way as in Example 1. The column called #ITOwnedItem:ITOwner:ITOwner:Person.name creates an ITOwnedItem:ITOwner:ITOwner relationship to a Person node with a name equal to Melnitz,J. The quotes around that field are needed because the field contains a comma.

After the quote, the #HostOnSubnet:HostSubnet:Subnet.name field begins with a '[' character. This field is converted into a list. Then, for each item in the list, a HostOnSubnet:HostSubnet:Subnet relationship is created to a Subnet node with a name attribute equal to that item. So the new host has one relationship to the 10.0.0.0/8 subnet and one to the 192.168.101.0/24 subnet.