JSON Entity Import File Format

A JSON entity import file is a plain text file that must be named with a ".json" file name extension, such as "entities.json". Each import file must contain a single JSON object with the following attributes (name/value pairs):

JSON Attributes	Required?	Comments
common_attributes	no	An array of other objects
entities	yes	An array of other objects
version	yes	A number representing the JSON file format version used. At the time this document was written, version 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. IO runs through the entire file before creating entities.

Warning

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
}

The common_attributes Element

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

description (optional) - the value is a string.
entity_types (optional) - the value is an array of entity types taken from the following list. Import is now case-sensitive.
- Application
- HostPort and/or StoragePort (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.
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 attributes.

In the following common_attributes example, two sets of tags are defined: one for hostport entities and another for host and hba entities. Also, there is a custom property called property1 that will be added to all entities in the file. ustom properties can only be included in the common_attributes section.

Note

Custom properties can only be included in the common_attributes section.

{
  "common_attributes": [
    {
      "entity_types": [
        "HostPort"
      ],
      "tags": [
        "HBA Port Device Aliases", // Example tag
        "JSONIMPORTED"    // Example tag
      ]
    },
    {
      "entity_types": [
        "Host",
        "HBA"
      ],
      "tags": [
        "Initiators",  // Example tag
        "JSONIMPORTED" // Example tag
      ]
    },
    {
      "addProperties": {
        "property1": "value1" // Example custom property
      }
    }
  ],
  "entities": [...],
  "version": 2
}

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.

The entities Element

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

name (required) - the value is a unique string that identifies the entity. It must be present for all types except fcport.
new_name (optional) - will override a discovered entity's name. If left blank in subsequent imports, entity names will be reverted to their discovered names. Note: name reversion does not apply to user-created entities.
description (optional) - the value is a string.
tags (optional) - the value is an array of strings.
child_entities
- The value is an array of entity names or, as appropriate, port WWNs (e.g., HBA Port or Storage Port entities).
- 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-level 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 (ITL) specifications for application entities only.
type - one of application, tier, host, hba, hostport, storagearray, storagecontroller, iomodule, or storageport.
wwn - the value is a string representation of a WWN; only used with hostport and storageport type entities.
edit_type - a string defined as either "add" or "modify"; the default is "modify".

Sample JSON File

A sample JSON file can be downloaded from IO. Go to Settings > Entity Import and then click on the appropriate link in the pane on the right side of the UI.

Importing Device Aliases

If you do not use aliases (nicknames for port WWNs), or if you do not use them in a consistent and coherent manner, then you might want to create them or to modify them, and then import them into IO. Without aliases, you only see FCIDs in the IO UI. Useful alias names are recommended to getting the most benefit out of using the Entity Creation Utility.

Alias import is done using either the hostport, storageport, or switchport type in a JSON import file. You can only perform alias mapping on the port level entities HBA Port, Storage Port, and Switch Port.

Tip: The examples that follow use a singleton array with JSONIMPORTED as the only entry. This is simply a best practice. Tags can be any valid string.

The port WWN displays with the assigned entity name rather than the WWN in all parts of the user interface.

Structure of an alias import file:

{
  "entities": [
    {
      "description": "description",
      "edit_type": "add",
      "new_name": "entity name", // Real entity name goes here
      "tags": ["JSONIMPORTED"], // Example tag
      "type": "hostport", // or "storageport" or "switchport"
      "wwn": "WWN" // Real WWN goes here
    }
  ],
  "version": 2
}

The hostport, storageport, and switchport types are only used for mapping aliases to existing port-level entities (HBA Port, Storage Port, and Switch Port).

Note that description and tags are optional elements, and edit_type defaults to add, so they are not explicitly required.

Example

{
  "entities": [
    {
      "description": "248d00059b2b78c0,fooserver_hba1 from customer.csv",
      "new_name": "fooserver_hba1",
      "tags": [
        "JSONIMPORTED"
      ],
      "type": "hostport",
      "wwn": "248d00059b2b78c0"
    },
    {
      "description": "5001438002b0dbb4,barstorage_port1 from customer.csv",
      "name": "barstorage_port1",
      "tags": [
        "JSONIMPORTED"
      ],
      "type": "storageport",
      "wwn": "5001438002b0dbb4"
    }
  ],
  "version": 2
}

When importing aliases, consider the following:

You can only import aliases for the discovered, port-level entities HBA Port and Storage Port. Switch port aliases are not supported.
You can override discovered aliases by providing an alternative name for a port WWN in an import file.
You can revert to a discovered name using an import where the name strings for a port WWN is the empty string, "".

HBA Card and Host Entities

The JSON file required for importing Host or HBA Card entities is similar to the device aliases (nicknames) import file, but there are some differences:

The type attribute is different. For HBA Card entities, the HBA type is used. For Host entities, the Host type is used.
A child_entities attribute is used with an add verb to specify child entities. The add verb overrides the edit_type attribute, so it doesn't need to be used.

Example

This example will create three entities: two HBA Port entities and one Host entity. Note the order in which entity specifications appear: the Host entity appears first in the file. But the Host entity depends on the two HBA Port entities. That is okay. IO will read and parse the entire file before figuring out which entities need to be created in what order.

{
  "entities": [
    {
      "child_entities": {
        "add": [
          "server1_hba0",
          "server1_hba1"
        ]
      },
      "description": "description text",
      "name": "server1",
      "tags": ["JSONIMPORTED"],
      "type": "Host"
    },
    {
      "child_entities": 
        "add": [
          "10000000c1234560",
          "10000000c1234561"
        ]
      },
      "description": "description text",
      "edit_type": "add",
      "name": "server1_hba0",
      "tags": ["JSONIMPORTED"],
      "type": "HBA"
    },
    {
      "child_entities": {
        "add": [
          "server1_hbaport2",
          "server1_hbaport3"
        ]
      },
      "description": "description text",
      "name": "server1_hba1",
      "tags": ["JSONIMPORTED"],
      "type": "HBA"
    }
  ],
  "version": 2
}

Storage I/O Module, Storage Controller, and Storage Array Entities

The process for creating Storage I/O Module, Storage Controller, and Storage Array entities is identical to creating HBA Card and Host entities, differing only by type. The types are IOModule, StorageController, and StorageArray respectively.

Example

{
  "entities": [
    {
      "child_entities": {
        "add": [
          ...
        ]
      },
      "description": "description text",
      "name": "name text",
      "tags": ["JSONIMPORTED"],
      "type": "IOModule" or "StorageController" or "StorageArray" // Pick one
    },
    {
      ...
    }
  ],
  "version": 2
}

Application Entities

The structure and content of an Application entities import file are very similar to the other hierarchical entities' import files. But instead of having a child_entities object, they have either an itl_patterns array or a devices object or both.

The devices object is identical in use to the child_entities object we've already seen.

The itl_patterns array contains objects consisting of the following elements:

edit_type (required) - needs to be set to add.
initiator (required) - set to the name of an HBA Port entity.
target (required) - set to the name of a Storage Port entity.
LUN (optional) - set to a LUN number or exclude, which means all LUNs.

Example

{
  "entities": [
    {
      "description": "description text",
      "devices": {
        "add": [
          "device1",
          "10.0.0.1:10.2.0.1:0",
          "10.0.0.3"
        ]
      },
      "itl_patterns": [
        {
          "edit_type": "add",
          "initiator": "somehbaport",
          "lun": 0,
          "target": "somestorageport"
        },
        {
          "edit_type": "add",
          "initiator": "somehbaport",
          "target": "somestorageport" // No LUN here means ALL LUNs
        }
      ],
      "name": "name text",
      "tags": ["JSONIMPORTED"],
      "type": "Application"
    }
  ],
  "version": 2
}

Adding Tier Entities

While you cannot add Tiers directly in Application entity JSON, you can add them separately.

Example

{
  "entities": [
    {
      "name" : "Tier Three",
      "type" : "Tier",
      "child_entities" : {
        "add" : [
          "app1",
          "app2",
          "app3"
        ]
      }
  ],
}

Renaming and Reverting Discovered Entities

Renaming Example

{
  "version": 2,
  "entities": [
    {
      "name": "esx-vm-01",
      "new_name": "MyVM",
      "type" : "VirtualMachine"
    }
  ]
}

Reverting Example

{
  "version": 2,
  "entities": [
    {
      "name": "MyVM",
      "new_name": "",
      "type" : "VirtualMachine"
    }
  ]
}

In this section:

JSON Entity Import File Format

Tip

Warning

Note

Importing Device Aliases

HBA Card and Host Entities

Storage I/O Module, Storage Controller, and Storage Array Entities

Application Entities

Search results