Importing CSV data
It is often very easy to extract information from applications and devices and store it as CSV data. Data can be exported from BMC Atrium Discovery in this format. For more information, see CSV API. You can also import CSV data into BMC Atrium Discovery (for example, you might have information on a number of hosts that you want to import).
You can import a CSV file using the Import CSV Data page described in the following section. You can choose delimiters other than commas when importing data using the Import CSV Data page. Alternatively, if you have command line access, you can use the tw_imp_csv utility.
Incorrect usage may result in data loss
Before using the Import CSV Data page you should fully understand the system taxonomy and the changes that you are going to make to your data. Using Import CSV Data incorrectly can cause irreparable damage to your data. The data you submit using this tool is applied directly to the production data without any validation.
Always back up your datastore before using this tool.
Do not import the following node kinds
- You must never import DDD nodes.
- You should avoid importing Host nodes and other system maintained nodes. If in doubt, contact Customer Support.
Importing a CSV file
To import a CSV data file:
From the Model section of the Administration tab, click CSV Import.
The following screen illustrates the Import CSV Data page with the Host Container node kind selected.
The options on this page are described below:
File To Upload
The file to upload. Click Browse... to display a file browser window.
Select the file to import and click Open.
Select the mode to use for updates. Choose one of the following from the list:
- Create And Update: nodes are created and updated as required.
- Create Only: new nodes are created, existing nodes are not updated.
- Update Only: new nodes are NOT created, existing nodes are updated.
- Delete Only: nodes with match are deleted. No other nodes will be created or updated.
Choose the type of node to import from the list. This may be one of any node kind defined in the taxonomy. Changing the node kind updates the Keys field dynamically.
Choose the key or keys for each entry. You must select at least one key. The taxonomy defined keys are marked with a red asterisk *. Use the checkboxes if you want to use other keys. The following quick selection links are provided at the top of the keys field:
- Key Attributes: selects just the taxonomy defined keys.
- None: clears any selection.
The behavior differs from the tw_imp_csv utility, which uses the first column of the input file as the key unless others are specified. When controlling an import using the UI Import page, only the keys that are selected are used.
Choose the required delimiter from the list. This may be Comma, Semicolon, or Tab.
Choose the logging level from the list. This may be Debug, Info, Warning, Error, or Critical.
- To import the CSV file, click Apply.
See CSV import examples for example of using the CSV importer.
Notes on the CSV importer
The CSV file represents a two dimensional table with rows separated by newlines, and columns separated by commas. Commas may be included in that data but must be enclosed between double quote characters.
Column names that do not begin with a hash character (#) are treated as names of attributes on the node.
Column names that begin with a hash character are treated as key expressions. Key expressions are used to create or update a relationship to another node. See Relationships for more information.
The CSV importer searches the datastore for nodes of a specified kind which have a key or keys matching rows in the supplied CSV data. Where the keys match, the node is updated, or deleted and recreated depending on the options selected. The first attribute column is used as a key by default. This can be overridden with the Keys option described in the table above.
Relationship columns describe a relationship between the node being modified and one or more other nodes. Relationships are defined using a full key expression. The first example shows a link to a single node:
This example shows a link to multiple target nodes. Notice that you will need to surround the relationship definition and data in double quotes so that the subsequent attributes do not get treated as local nodes:
The first role part is the kind of the role that the node being created or updated plays in the relationship. The relationship part is the kind of the relationship being created. The second role part is the kind of role that the other node plays in the relationship. The kind part is the node kind of the other node. Finally, the attribute or attribute list is the name of the attribute used to find the other node. See the Node Lifecycle Document for information on relationships.
Only a single traversal is supported.
By default, the CSV importer attempts to convert attribute values to the type defined in the taxonomy. If an attribute is not defined, it is left as a string. If a conversion fails, it is also left as a string.
For list types, the value in the CSV file must be in Python list syntax.
When the tw_imp_csv utility is used with the
--force option, all attributes are left as strings.