XML import file reference

Field reference for the XML device import file format used in VHQ.

What is the XML import format?

You can add, modify, or delete one or more devices by using an .xml file.

Sample Device .XML File

XML attribute reference

XML Tag	Optional / Required	Tag / Attribute	Description
Version	Mandatory	Tag	VHQ data version.
Hierarchies	Mandatory	Tag	Device hierarchy.
Hierarchy	Mandatory	Tag	Device hierarchy.
Operation	Mandatory	Attribute	Operations performed on hierarchy — A: Add, U: Update, D: Delete.
Hierarchy Name	Mandatory	Attribute	Name of the hierarchy the device is assigned to.
ParentHierarchyPath	Optional	Attribute	Complete path to the hierarchy from the root node, using ">>" as the separator. Example: MyCompany>>MyRegion>>MyState>>MyCity>>MyStore. If the operation is ADD, ADD_MODIFY, or MODIFY, a value must be specified, or VHQ assumes the root node.
Time zone	Optional	Attribute	Hierarchy time zone.
IPAddressStart	Optional	Attribute	Hierarchy IP start address.
IPAddressEnd	Optional	Attribute	Hierarchy IP end address.
Description	Optional	Attribute	Hierarchy description.
Groups	Optional	Tag	Device group.
Group	Optional	Tag	Device group.
Operation	Mandatory	Attribute	Operations performed on group — A: Add, U: Update, D: Delete.
GroupName	Optional	Attribute	Name of the group the device is assigned to.
Description	Optional	Attribute	Group description.
Devices	Mandatory	Tag	Devices to be added in VHQ.
Device	Mandatory	Tag	Device in VHQ.
Operation	Mandatory	Attribute	Operations performed on the device — A: Add, UA: Update and add, U: Update, D: Delete, DA: Delete and add.
SN	Optional	Attribute	Serial number of the device being created or modified. Maximum length 255 characters; format is nnn-nnn-nnn, not validated by the import tool.
DID	Mandatory	Attribute	Device unique identifier.
Model	Mandatory	Attribute	Device model ID.
IdentifierType	Mandatory	Attribute	Device or terminal identifier used to reference the device — not the internal unique device identifier.
HierarchyPath	Optional	Attribute	Complete path to the hierarchy from the root node, using ">>" as the separator. Same rules as ParentHierarchyPath above.
HierarchyName	Optional	Attribute	Name of the hierarchy the device is assigned to.
IPAddress	Optional	Attribute	IP address of the device.
Status	Optional	Attribute	Device status — Pending Registration, Pending Hierarchy Assignment, Active, Inactive, Deleted Devices, Blacklisted Devices.
Groups	Optional	Attribute	Associates a device to an already existing group in VHQ.
DownloadOptions	Optional	Tag	Download options.
AutomationEnabled	Optional	Attribute	Whether download automation is enabled.
Software	Optional	Tag	Software on the device.
AssociationType	Optional	Attribute	Software association type — Package or Reference Set.
Packages	Optional	Tag	A Software Package is a group of applications bundled and compressed as a .TGZ or .ZIP file in a pre-defined structure. Bundles (.TGZ) for V/OS devices and VPI Packages (.ZIP) for eVo devices can be imported and configured as Packages in VHQ.
Package	Optional	Attribute	Software package assigned to the device.
Operation	Mandatory	Attribute	Package operation — A: Assign, D: Unassign/delete, U: Update.
Name	Mandatory	Attribute	Name of the package.
PreviousPackage	Optional	Attribute	Previous package(s) assigned to the device.
UpgradablePackage	Optional	Attribute	Package available for upgrade.
Applications	Optional	Tag	VHQ users configure Software Packages by importing VPI Packages and Bundles. VHQ extracts the application name and version from metadata files based on package type. Multiple applications form a package; multiple packages form a bundle.
Application	Optional	Tag	Indicates the application.
Name	Mandatory	Attribute	Application name.
Version	Mandatory	Attribute	Application version. Setting this to the special value Current (case-insensitive) applies any parameters in the associated Parameters element to whichever version of the application is presently assigned to the device.
ReferenceSet	Optional	Tag	Reference set assigned to the device. VHQ evaluates and identifies one reference set that qualifies for each device.
Name	Optional	Attribute	Reference set name.
ParameterTemplates	Optional	Tag	Parameter Templates let you manage a common set of parameters that apply to a group of devices. Changing a template's values applies them to all associated devices. You can configure one or more templates per application. 1. Extra parameter templates defined in the XML are appended to the existing assignment, added at the end of the device's existing template list. 2. The order of templates in the XML is the order in which they're assigned to the device.
Parameters	Optional	Tag	Parameters assigned to the device.
Parameter	Optional	Tag	Parameters assigned to the device.
Operation	Mandatory	Attribute	Parameter operation — A: Add, UA: Update and add, U: Update.
Name	Optional	Attribute	Device parameter name.
Value	Optional	Attribute	Parameter value.
XPath	Optional	Attribute	Parameter path.

• DID is considered present.
• Parameter validation must be done.
• Auditing information must be added.
• If HierarchyPath is blank, the import tool uses HierarchyName to place the device in the appropriate hierarchy node. The operation fails if there are multiple nodes with the same name. For an Update (U) operation, a device's status can be updated to Inactive or Deleted — in either case, software assignment will fail and its application parameters can't be updated.

Device import result XML file

You can view the device import results by downloading the results .xml file from Device Management > Import/Export > Import. The XML file is displayed.

Sample Device Result .XML File

The VHQ import tool generates an import status XML output file describing the processing status of each device record, named <Import_File_Name>_<VHQ user ID of the user who initiated the import>_YYYYMMDDHH24MISS.xml, accessible from the VHQ GUI.

Summary results include:

• Total number of device records in the XML input file.
• Number of device records successfully processed.
• Number of device records rejected, with a breakdown of the error count for each error code.

Detailed results, for each rejected record, include:

• A dump of the device record from the input file.
• An error code with a descriptive message indicating why the record wasn't processed.

See the Device import error codes reference for the full list of error codes VHQ can return.

Related topics

• Adding devices via file import
• CSV import file reference
• Device import error codes