CSV Entity Import File Format

For existing customers currently using the Entity Import feature using JSON files, CSV import provides for only a subset of the features supported by JSON import. Please note the following differences.

  • CSV import cannot be used to

    • Populate the entity description field

    • Create device aliases for HBA Port or Storage Port entities

    • Create Tier definitions for Application entities

    • Add ITLs to Application entities

  • Use of WWNs in place of entity names for port-level devices is not supported.

A CSV entity import file is a ZIP file containing two CSV files. The first CSV file is a mapping file and must be named "mapping.csv". The second CSV file is the data file that contains descriptions of entities that will either be created or modified.

Mapping File (CSV)

The mapping file is one of the required files in a CSV import ZIP file. It is essentially a roadmap for how VirtualWisdom will identify content in the data CSV file. The mapping file consists of the following columns. The order in which columns appear in the mapping file is irrelevant.

Column Name

Required?

Description

file_name

yes

The name of the data file with no path information. The data file must reside in the same directory as the mapping file in the ZIP file.

skip_rows

no

Skip the specified number of rows from the data file after the header row. If the value is either empty or not present in the mapping file, the default is 0.

entity_lookup_id

no

How an existing entity will be identified. There are two possible values:

  • name

    This is the default if the value is either empty or not present in the mapping file.

  • ip

    If this value is specified for an entity type that does not support IP address lookup, an error will be reported.

    Please note: the supported entity types that can be searched by IP address are: Host, VirtualMachine (ESX VM), Partition (PowerVM Partition), HyperVVM (Hyper-V VM), and other entities of type host and virtual host with assigned IP address (e.g., KVMCapiHost/KVMCapiVirtualHost (KVM Host/KVM Virtual Host)).

entity_lookup_col

yes

The name of the entity lookup column in the data file.

entity_type

no

The entity type name as defined internally by Virtana. The following entity types are supported for entity creation and for device modification: Application, Host, HBA (HBA Card), IOModule (Storage I/O Module), StorageController, and StorageArray.

If the field is either empty or not present in the mapping file, the import utility attempts to detect the type for an existing entity. If a new entity is being created, the default value Application is used. This field is associated with the entity_lookup_col. If the entity_lookup_id column is set to ip, this column must be set.

device_lookup_id

no

Note

The fields starting with device_ are used when adding or modifying child entities to container entities, such as Applications.

How an existing device entity will be identified; same options as entity_lookup_id.

device_lookup_col

maybe

The name of device lookup column in the data file. This is required if the device should be associated with an entity.

device_type

no

The entity type name as defined internally by Virtana. The same entities that can be added to user-created entities in VirtualWisdom may be used here.

If the field is either empty or not present in the mapping file, the import utility attempts to detect the type for an existing entity. This field is associated with the device_lookup_col column. If device_lookup_id is set to ip, this column must be set.

entity_tag

no

Zero or more columns can be added with this column name, each column representing one tag. The value specifies the name of a tags column in the data file. If multiple columns are specified with this column name, multiple tags are assigned to the imported entity.

entity_custom_prop

no

Zero or more columns can be added with this column name, each column representing one custom property. The value is the name of column in the data file which represents a custom property. The column name in the data file is the key of the custom property.

replace_properties

no

If set to true, all the existing custom properties associated with the entity will be replaced. The default value is true.

replace_devices

no

If set to true, all the existing devices associated with the entity will be replaced. The default value is true.

Data File (CSV)

The data file contains information about each entity that will either be created or updated upon import. The file must have a header row which names each column. The column names are derived from the columns in the mapping file. If the field values in the file contain characters which are not allowed or readable by VW, those rows will be skipped from import. The order in which columns appear in the mapping file is irrelevant.

Warning

You cannot use any of the following characters for tags or custom property columns:

, ; * ? < > | + % ~ & = [ ]

Sample Mapping File (mapping.csv)

csvmappingfilesample.png

In this example, the mapping file defines settings for Application creation and/or modification. Each Application defined in the associated data file (see below) will have a number of child entities defined by their names and will have three tags and two custom properties each. Column explanations follow in the left-to-right they appear in the file.

  • The associated data file name must be apps.csv

  • Zero rows will be skipped. As this is the default, this column could be omitted.

  • Entities will be searched by name.

  • Entity names will be located in the "app" column in the data file.

  • Only Application entities will be added or modified.

  • Application devices (child entities) will be identified in VirtualWisdom by name.

  • Device names will be located in the "server" column in the data file.

  • Three tags will be added to each Application entity, identified by the "function", "environment", and "import_tab" columns in the data file.

  • Two custom properties will be added to each Application, identified by the "data center" and "location" columns in the data file.

Sample Data File (apps.csv)

csvdatafilesample.png

In this example, five total Application entities will either be created, if they don't currently exist, or be modified. Two of the Applications will have more than one device (child entity): "devops" and "nas_prod".