Software Configuration

Learn more about configuring applications, configuring packages, and configuring reference sets. 

You can configure applications that run on a device. The Model that a device belongs to determine the type of application that you configure for the device. Currently, based on the Device Platform, various packaging tools and procedures are being followed that in turn define the packaging structure and the content of these Software Packages.

  1. For eVo based devices VPI packages (.ZIP) are used. Each application is in the form of a .ZIP file. Multiple Application files are compressed to create a VPI Package. VPI Package contains additional supporting files such as .man file that defines the order in which the applications in a VPI Package should be unzipped on the device (after the main VPI Package is downloaded to the Device).
  2. For V/OS based devices Software Bundles and Bundle of Bundles are used. Each application is in the form of .Tar file. Multiple Applications are grouped to form a Package and Multiple Packages are grouped to form a Bundle.

VHQ users configure Software Packages by importing the VPI Packages and Bundles. VHQ processes these packages to extract and set up the applications. VHQ extracts the application name and version from specific metadata files based on the type of the package.


Configuring Packages

Software Package is a group of applications bundled either in a .ZIP and .TGZ formats for eVo and V/OS based devices respectively. VPI Packages (eVo) and Mx Bundles (V/OS) can be imported as Packages in VHQ. 

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 based Devices VPI Packages (.ZIP) for eVo based devices can be imported and configured as Packages in VHQ.

NOTE:  For the devices enabled for Automated Download, VHQ triggers a download in case the Applications on Server do not match with the Applications on Device. Only the packages qualified for Automated Download, are available while creating a reference set.

The VHQ users configure software packages by importing the VPI Packages and Bundles. VHQ processes these packages to extract and set up the applications. VHQ extracts the application name and version from specific metadata files based on the type of the package.

NOTE: Same Application could be packaged as part of different Software Packages.


Package Structure

Structure of Bundle of Bundles (V/OS Based Devices)

V/OS bundle is a collection of one or more packages signed and downloaded as a single unit on V/OS based devices. It is simply an archive containing one or more signed packages (optionally includes signer certificates and a special 'remove' file).

Below example, has 2 Bundles – Bundle1.TGZ and Bundle2.TGZ. Each one has corresponding signature files (.p7s).

Multiple Bundles are further compressed wrapped using a Bundle Container. (BundleContainer.TGZ to form Bundle of Bundles. Bundle of Bundles can contain one or more Bundles.)

A single Bundle or Bundle of Bundles can be imported into VHQ and set up as a VHQ Package. The contained V/OS Packages (Package1.tar and Package2.tar) are extracted and set up as VHQ Applications. Control File#1 defines the Bundle Name and Version of Bundle1.TGZ, Control File#1.1 and Control File#1.2 define the Package Name and Version for the Packages Package1.tar and Package2.tar respectively

The bundles are built by the Corresponding SE (Sales Executives) using Secure Installer.

Structure of Bundle of Bundles (V/OS Based Devices)

Bundle Structure

V/OS Terminology and Description

VHQ Terminology/

Representation

BundleContainer.TGZ

Main Bundle container

Package

Bundle1.TGZ

Bundle

Control File#1

Defines bundle name and version

Package1.tar

Package

Application

Control File#1.1

Defines Package name and version

Application

Name and Version

Package2.tar

Package

Application

Control File#1.2

Defines Package name and version

Application

Name and Version

Bundle1.TGZ.p7s

Bundle signature

Bundle2.TGZ

Bundle

Package

Control File

#2

Defines bundle name and version

Package3.tar

Package

Application

Control File#2.1

Defines Package name and version

Application

Name and Version

Package4.tar

Package

Application

Control File#2.2

Defines Package name and version

Application

Name and Version

Bundle2.TGZ.p7s

Bundle signature

NOTE:

  1. A V/OS Bundle is configured as a Package in VHQ and a package (contained in the V/OS bundle) is configured as an Application.
  2. For the devices enabled for Automated Download, VHQ downloads the Bundles that do not match the Bundles on Device. Bundle Name and Version defined in Control Files (Control File#1 for Package1, Control File#2 for Package2) forms the basis of evaluating the Software version setup on VHQ. Only the Bundles that have Control files qualify for Automated downloads.
  3. Only the VHQ Packages qualified for Automated Download, are available while creating a reference set.

Structure of VPI Package

VPI Package (.ZIP) is a collection of one or more applications. Each application (.ZIP) is downloaded as a single unit on eVo based devices.

Below example, has a main VPI Package (MainVPI.ZIP) that has two Applications. (Application1.ZIP and Application2.ZIP.)

VPI Structure

eVo Terminology and Description

VHQ Terminology/

Representation

MainVPI.ZIP

Main VPI Container

Package

Manifest File#0

Defines Package name and version

Package name and version

Application1.ZIP

Application

Application

Manifest File#1

Defines Application name and version

Application

Name and Version

Binaries/

Configuration files

Application2.ZIP

Application

Application

Manifest File#2

Defines Application name and version

Application

Name and Version

Binaries/

Configuration files

VPI Package can be imported into VHQ and set up as a VHQ Package. The contained V/OS Applications (Application1.ZIP and Application2.ZIP) are extracted and set up as VHQ Applications. Manifest File#0 defines the Package Name and Version, Manifest File#1 and Manifest File#2 define the Application Name and Version for the Applications Application1.ZIP and Application2.ZIP respectively.

The VPI Packages are built by the Corresponding SE (Sales Executives) using VPI Package Installers.

NOTE:

  1. For the devices enabled for Automated Download, VHQ compares Application Name and Version defined in Manifest Files (Manifest File#1 for Application1, Manifest File#2 for Application1) against the Application Name and Version as reported by Device and downloads the Applications that do not match.
  2. Only the VPI Packages that have Manifest files qualify for Automated downloads.
  3. Only the VHQ Packages qualified for Automated Download, are available while creating a Reference set.

Editing a Package

You can edit packages from the Download Library.

To edit package:

  1. Go to Device Management > Manage Downloads > Download Library.
  2. Select the package in the Download Library screen and then click (Edit Package) to edit. You cannot edit the Package file and the Package name.
  3. Click Save. The package gets successfully updated.

Deleting a Package

You can delete packages from the Download Library.

To delete a package:

  1. Go to Device Management > Manage Downloads > Download Library.
  2. Select the package in the Download Library screen.
  3. Click (Delete Package). The Confirmation message box is displayed. Click Yes to delete the package or click No to close the Confirmation message box. 

Viewing Applications

To view applications:

  1. Go to Device Management > Manage Downloads > Applications Library.

The grid lists all the application setup on VHQ and the parent packages they belong. You can now upload individual applications to the Applications Library tab device directly from the Applications tab. The applications extracted from software packages upload in the download library cannot be edited or deleted. You can only edit and delete the applications uploaded directly through Application Library tab.

NOTE: There can be common applications extracted from multiple packages.


Uploading a Package

You can add software package.

To add software package:

  1. Go to Device Management > Manage Downloads > Download Library.
  2. Click (Add Package) to add package to download library.
  3. Browse and select the package to upload. You can upload Bundles (.TGZ, .tar files) for V/OS based Devices, VPI Packages (.ZIP files) for eVo based Devices to configure Software Packages. The packages .bintbl extension will be used for VCL BIN Table Updates. The max length of file name, for packages uploaded to the VHQ download library is 248 characters. Although the VHQ GUI allows a package to be uploaded, whose file name length is up to 248 characters, the actual length of the package file satisfies the additional constraint given below, based on the device to which this package will be downloaded.
  • For MX8xx and MX760 devices, the maximum length of package file name must not exceed 32 characters.
  • For Verix eVo devices, the maximum length of package file name must not exceed 32 characters.
  • For MX9xx and Ux devices, the maximum length of package file name must not exceed 85 characters.
  1. Enter the Package Name in the box.
  2. Select device models to which the package is compatible from the Model(s) drop-down list. If you want to include all the models, select All Models check box.
  3. Select the Package Type in the drop-down list.
  4. Enter the Package Version and Tags in the respective boxes. You can use the Tags to search for the Package in the Download Library.

Specify the post installation action to either reboot or restart the application(s) or none.

NOTE: The V/OS bundles must contain the control files to qualify for Automated downloads. VPI Packages must contain Manifest files to qualify for Automated downloads. For more details, refer the structure of V/OS Bundles and VPI Packages.

  1. Click Add. The Package is successfully added to the Download Library.
  2. You can view the applications that are part of imported packages under the Applications tab.

NOTE:

1. The Package Type and File version are used only for the user information. These details are not used as part of any processing logic.

2. The Post Install Action is not available for some of the Packages. For such Packages, VHQ Agent on Device takes care of the required Post install actions.

3. The Post Install Action Restart Application (s) does not restart the VHQ Agent application in a device, but restarts all other applications running on a device. If VHQ Agent must be restarted after downloading a file to a device, then the Reboot post-install option should be selected before uploading the given file to the VHQ server library.


Viewing Software Packages

The Download Library is a central repository of all the Software Packages configured on VHQ. You can manage the Software Packages from Download Library.

The Download Library screen includes the following fields and their description:

Fields

Description

Package Name

Indicates the package name of the device.

Models

Indicates the device model name.

File

Indicates the file in the package.

File Size (KB)

Indicates the maximum size of the file.

Package Type

Indicates the package type. (Bundle, Application, Service Pack)

File Version

Indicates the file version.

Package Category

Indicates the package category.

Component

Indicates the package component such as Payment Device, Tablet, or Payment Device & Tablet.

Post Install Action

Indicates any action to be performed after installation.

Tags

Indicates the tags.

Automatic Download

Indicates if the automatic download is allowed or not.

Uploaded By

Indicates the name of the uploader.

Uploaded On

Indicates the date and time of the upload.

Applications

Indicates the applications in the package. Click View link to view the applications.

NOTE: Parameter attributes for an application are set when you add a new application. You can, however, add new parameter attributes to an existing application or modify them. For more details on Parameter Attributes configuration refer to the Parameter Management section.


How Packages are Compatible for Autodownload?

The packages with Manifest files qualify for Autodownload and Control files qualify for Manual downloads.


Configuring Reference Sets

Reference set is a logical container that comprises of:

  1. Set of Packages and their order of download.
  2. List of Device Models for which the Reference set is compatible.
  3. Matching criteria that define which Devices in the Hierarchy qualify for this Reference set.
  4. Reference Set can be assigned to hierarchy or directly to Devices.
    • Reference set assigned to a Hierarchy is used to evaluate the Software that needs to be associated with a set of Devices in a Hierarchy and its child Hierarchies.
  1. Reference set assigned directly to a Device identifies the Software that needs to be associated with that Device.
  2. VHQ evaluates and identifies one Reference Set that best qualifies for each Device.
    • For complete set rules on how VHQ evaluates the best qualifying Reference Set for each Device.

Adding Reference Set

You can create a reference set and asign up to 100 packages to the reference set. The number of packages, the user can assign to the reference set can be configured in “Maximum Packages Per Reference Set” under Administration > Estate Administration > System Configuration. The VHQ Administrator can configure the value.

NOTE: VHQ Agent version older than 2.11 will not be able to process operation sets with more than hundred packages, only devices which have VHQ agent version 2.11 or higher will be able to process operation sets with more than hundred packages. However, for the devices which have VHQ Agent version older than 2.11 the operation set will be divided with each containing 10 packages.

To create reference set:

  1. Go to Device Management > Manage Reference Sets > Reference Sets.
  2. Click to add the Reference Set.
  3. Enter the Reference set name. Select Packages and the order in which they must be downloaded. Select the Device Models with which the Reference Set is compatible.
  4. You can define the required Matching criteria in case the Reference set should be associated with devices with specific attribute values.
  5. Click to add attributes to the Matching criteria. The Attributes cannot be repeated at the time of creating Reference Set.

In the process of defining a reference set (editing is in progress) you can turn off Active setting and Save the Reference Set. You can edit the Reference Set later and set it to Active. Only Active Reference Sets are available for assignment to Hierarchy or Devices.

NOTE: Once a user chooses a particular attribute, for example, IP Address, OS Version etc., the user cannot choose the same attribute again to filter. An attribute can be used only once to apply.

Attribute

Description

OS Version

Indicates the device OS (Operating System) version. 

GUI Manager Version

Indicates the GUI manager version.

VHQ Version

Indicates the VHQ device agent version.

Location Identifier

Indicates the location identifier of the device.

M-Level Part Number

Indicates the part number of the device.

HW Device

Indicates the hardware device attribute or parameter and has the value of the smartcard reader software version.

IP Address

Indicates the IP address of the device.

MAC Address

Indicates the MAC (unique identifier) address of the device.

POS Agent Version

Indicates the POS (Point of sale) device agent version.

POS OS Version

Indicates the POS (Point of sale) OS version.

POS IP Address

Indicates the POS (Point of sale) IP address.

Editing Reference Set

You can also edit the reference set.

To edit reference set:

  1. Select the reference set listed on Reference Sets screen.
  2. Click Edit icon. Only Active Reference Sets are available for assignment to Hierarchy or Devices.

If you have already assigned this Reference Set to Hierarchies and Devices and you want to stop all the future downloads that are related to this Reference Set, you can turn off the Active setting.

Deleting Reference Set

You can delete the associated Reference Set assigned to the multiple devices and hierarchy node.

To delete the reference set:

  1. Go to Device Management > Manage Reference Sets > Reference Sets.
  2. Select the Reference Set (s).
  3. Click Delete icon. The selected reference sets association with Devices and Hierarchies are removed.

Copy Reference Set

You can also copy the reference set.

To copy reference set:

    1. Select the reference set listed on Reference Sets screen.
    2. Click to copy, reference set. This feature copies the packages, models and device attribute of the existing reference sets.
    3. You must provide a Reference set name and click Save.