Entity Import File Format

You must create a JavaScript Object Notation (JSON) file that you use to import entities into VirtualWisdom. Only JSON v2 is supported.

Entities to be imported into VirtualWisdom must be specified in a plain text file with a “.json” file name extension, such as “entity.json”.

Entity import files consist of a JSON object with three name/value pairs:

Table 75.

JSON Name/Value Pairs

Required or Optional

Comments

common_attributes

Optional

An array of other objects

entities

Required

An array of other objects

version

Required

The JSON file format version used; a standalone name/value pair that must be set to 2



Tip: The order of the objects in the JSON file is irrelevant. Parent and child entities can be created in any order. VirtualWisdom runs through the entire file before creating entities.

You cannot use any of the following characters for name and tags fields:

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

Following is an example of a basic import file:

{

"common_attributes": [...],

"entities": [...],

"version": 2

}

common_attributes

These are shortcuts used to provide common descriptions, tags, and custom properties to entities contained in an input file. They are a container for objects consisting of the following member pairs:

  • description (optional)

The value is a string.

  • entity_types (optional)

    • The value is an array of entity types taken from the following list:

      • application

      • fcport (used to provide aliases for either HBA Port or Storage Port entities)

      • hba

      • host

      • iomodule

      • storagearray

      • storagecontroller

    • If the value is not null, then the attributes apply to all entities of the listed types contained in the file.

    • If the value is null, then the attributes apply to all entities contained in the file.

    • For custom properties, entity_types cannot be used, so you need to be careful how you apply custom properties to entities.

  • tags (optional)

The value is an array of strings.

  • addProperties (optional)

The value is an object containing custom property name/value pairs.

In the following common_attributes example, two tags are defined: one for fcport entities and another for host and hba entities.

Each entity in the import file has a custom property called property1 added to it. Custom properties can only be included in the common_attributes section.

Typically, JSON files are constructed using tools that automate the process (e.g., converting a CSV to JSON), so tags and description are specified in-line rather than abstracted out. As a result, the remaining examples do not use common_attributes, to reflect that more common scenario.

{

"common_attributes": [

{

"entity_types": [

"fcport"

],

"tags": [

"Device Aliases",

"JSONIMPORTED"

]

},

{

"entity_types": [

"host",

"hba"

],

"tags": [

"Initiators",

"JSONIMPORTED"

]

},

{

"addProperties": {

"property1": "value1"

}

}

],

"entities": [...],

"version": 2

}

entities

The entities attribute is an array of objects consisting of the following possible member pairs:

  • name

    • The value is a unique string that identifies the entity.

    • It must be present for all types except fcport.

  • description(optional)

    • The value is a string.

  • tags(optional)

    • The value is an array of strings.

    • Tags can be any valid string.

  • child_entities

    • The value is an array of entity names or, as appropriate, port WWNs.

    • They can be existing user-created or discovered entities, or entities being imported in the same import file.

    • Specify child entity identifiers by WWN if child entities are port entities.

    • Specify by name of entity for user-created child entities.

  • devices

    • The same as child_entities, but only used with application entities.

  • itl_patterns

    • The value is an array of initiator, target, and LUN specifications forapplicationentities only.

  • type

    • application, tier, host, hba, storagearray, storagecontroller, iomodule, or fcport

  • wwn

    • This is only used withfcporttype entities.

  • edit_type

    • Defaults to "add", so it might be excluded from the import file.