Parameter Management

Learn more about parameter configuration, parameter templates, editing paramter values and validating parameters that are downloaded to the device.

Applications on Device comprise of a set of executables and configuration files. Configuration files store the Application parameters.

The Parameter Management feature makes it easier for the user to configure, edit, download and manage the values of these application parameters. The user defines, configure values and download the application (including OS) parameters to the devices.

Parameter Management includes:

  • Setup/definition phase that involves setting up all pre-requisite configurations to enable Parameter Management.
    • Configuration of Software Packages and Applications.
    • Importing Parameter Definitions for the Applications.
    • Preparing and Importing Parameter Form View Files for the Applications.
    • Configuring Parameter Templates for the Applications.
  • Configuration phase that involves identifying the Parameters (and their values) that need to managed for specific devices. It includes:
    • Assigning Software Packages to Devices.
    • Assigning Application Parameter Templates to Devices.
    • Configuring the Parameter values for specific Applications for specific Devices as required.
  • Downloads/Synchronize phase VHQ evaluates and builds the list of parameters that need to be downloaded in the appropriate format and downloads them to the device.

Parameter Configuration

 Applications on Device comprise of a set of executables and configuration files. Configuration files store the Application parameters.

The Parameter Management feature makes it easier for the user to configure, edit, download and manage the values of these application parameters. The user defines, configure values and download the application (including OS) parameters to the devices.

Parameter Management includes:

Setup/definition phase that involves setting up all pre-requisite configurations to enable Parameter Management.

  1. Configuration of Software Packages and Applications.
  2. Importing Parameter Definitions for the Applications.
  3. Preparing and Importing Parameter Form View Files for the Applications.
  4. Configuring Parameter Templates for the Applications.

Configuration phase that involves identifying the Parameters (and their values) that need to managed for specific devices. It includes:

  1. Assigning Software Packages to Devices.
  2. Assigning Application Parameter Templates to Devices.
  3. Configuring the Parameter values for specific Applications for specific Devices as required.

Downloads/Synchronize phase VHQ evaluates and builds the list of parameters that need to be downloaded in the appropriate format and downloads them to the device.

NOTE: VHQ supports parameter downloads only using Automated downloads.

The VHQ full Parameter downloads take place:

  1. When a package is assigned to a device for the first time.
  2. When existing Package 1.0 is being replaced by Package2.0. (Whenever package assignment is changed, full parameters will be downloaded).

VHQ supports the internationalization of parameters values to end users that cannot understand language, currency or data formats that are currently used in VHQ. This feature gives local user an advantage to edit or update parameter values in VHQ.

The VPDX and VPFX files support UTF-8 (8-bit Unicode Transformation Format) for parameter values. Similarly, all validation related attributes in VPFX file also supports the UTF-8 for internationalization of parameter value. UTF-8 language setting is defined in VPDX and VPFX files. However, at a time one Application version can support one language.

EXAMPLE: If the values are defined in VPDX and VPFX are in Hebrew language for a particular application version, users can view and edit values in Hebrew language only. 


Importing Parameter Definitions for Applications

As part of the VHQ Parameter Management process flow, the Application developers need to build a Parameter Definition file that defines all Parameters of the Application and their attributes.

Parameter Definition File is an XML file with the extension .vpdx.

This file defines:

  1. Names of Application Parameters, their organization into groups and default value.
  2. Name of the Parameter file on the Device.
  3. Format and structure of the Parameter files on the Device.

For more details about the Parameter Definition File, refer to the Parameter Form File section.

To configure parameter definitions for application:

  1. Go to Device Management > Manage Downloads > Applications Library.
  2. Select the application and click Configure link in Parameter Definitions column for the respective application.

NOTE: The Parameter Definition File can only be uploaded once.(Current Implementation)

  1. The Parameter Definition File for Applications provides three options:
      1. New: Select this option to select and import a new Parameter Definition file. Browse to select the parameter definition file.
      2. Reuse from other versions: Select this option to select Parameter Definition file from other versions of the selected application.
      3. None: Indicates no parameter definition file is selected.

EXAMPLE: The user has imported Parameter definition file for Application App1 version 1.0. Now there is a new version of the Application available App1 1.1. App1 1.1 has some issue fixes and there are no changes to the Parameters. In this case, you can reuse the Parameter definitions which were already set up for App1 1.0.

  1. Click Browse to select the parameter definition file.
  2. Click View Parameters link to view the parameter name and the parameter default value.
  3. Click OK to proceed and Save to apply the changes.

Preparing and Importing Parameter Form File

VHQ provides a user friendly interface for editing application parameters using Form file. Application parameters stored on Device can have cryptic names. The parameter values can be of specific types (string, numeric) and must have the permitted set of values.

For each parameter in Parameter Definition file, the Parameter Form file defines:

  1. User friendly name shown in the GUI.
  2. Description of the parameter.
  3. Default value.
  4. Rending control – text box, drop list, numeric etc.,
  5. Validation rules for parameter value.

NOTE: For editing the Parameters of an Application using VHQ GUI, the Parameter form file should be configured for the Application.

PFX is typically prepared by Customer Administrators, Regional Support representatives or VHQ Support personnel.

For more details about the Parameter form file, refer to the Parameter Form File section.

To configure Parameter Form file for an Application:

  • Go to Device Management > Manage Downloads > Applications Library.
  • Click the Configure link in Parameter Form View File column on the selected application.
  • The Parameter Form View File for Applications provides three options:
      • New: Select this option to select and import a new Parameter Form View file. Browse to select the parameter form view file.
      • Reuse from other versions: Select this option to select the Parameter Form View file from other versions of the selected application. You can add a description to the Parameter Form View file in the Description box.

None: Indicates no parameter form view file is selected.

  • Click Save to apply the changes.

EXAMPLE: The user has imported Parameter Form view file for Application App1 version 1.0. Now, there is a new version of the Application available App1 1.1. App1 1.1 has some issue fixes and there are no changes to the Parameters. In this case, you can reuse the Parameter Form view file which was already set up for App1 1.0.


Parameter Definition File

ParameterElements > ParameterFile

ParameterFile > Name

ParameterFile > Format

ParameterElements > ParameterFile > Container

Container > Name

Alternate option: XSD has provision to provide documentation. Explore if we can use the same.

XML Elements

Or Attribute

Description

ParameterElements

Parent XML Element that contains one more ParameterFile elements.

Each ParameterFile element defines details of one Parameter File

Version

Version of the Parameter Definition file

ParameterFile

Details of Parameter file on Device.

In case Application stores its parameters in multiple Parameter files, you can have multiple Parameter File sections.

Name

Name of the Parameter file on the Device.

Format

Format of the parameter file.

POINT- For POINT customers. VHQ downloads only the changed Parameters.

Config.sys - For Vx devices that store their parameters in different GIDs. VHQ downloads all the Parameters that are part of the Parameter File section.

Config.$$$ - For Vx devices that store their parameters in different GIDs. VHQ downloads only the changed Parameters.

ADKH - For Applications that store their parameters using ADK Information Services in Hierarchical format. VHQ downloads all the Parameters that are part of the Parameter File section.

ADK - For Applications that store their parameters using ADK Information Services in Tabular or flat format. VHQ downloads only the changed Parameters.

Container

Multiple Parameters can be grouped into groups, categories or sections using Containers for better organization. Containers can be organized in a hierarchical structure.

Name

Name of the Container.

For Parameter file with Config.sys or Config.$$$ format

There should be one main Container (under the ParameterFile)

with name,

GID:<Group Id where the parameters should be downloaded>

Example: GID:7 – to download the parameters to GID 7

or

GID: $APPGID$

User can set the Application GID for an Application using the VHQ GUI.

The value as specified in the VHQ GUI for this application will be used in place of $APPGID$

Example: If an Application has $APPGID$ set to 7, the parameters will be downloaded to GID 7

Param

Parameter

Name

Name of the Parameter.

Default

Default value of the parameter.

OutFileFormat

For Parameter file with ADKH or ADK format – this section should contain the complete XML content of the ADK format file.

NOTE: Applications that use ADK Information Services (for storing their parameters on Device) are shipped with Schema file and Format file – that define the structure of Parameters and structure of the parameter file respectively

Parameter Form File

PFX is used to provide a user friendly interface for editing Application parameters.

PFX is an xml file with extension .vpfx

To create a PFX file, you can make a copy of the parameter definition file and rename the extension to .vpfx

Content and structure of PFX file is very much similar to PDX file. You need to provide values for additional attributes for each Parameter that define its user friendly name, description, rendering controls, data type, validation rules etc.

NOTE: Core XML elements and attributes in the PFX file are same as that in PDX file. For more details on these elements/attributes, refer to the Parameter Definition File section.

XML Entity/Attribute

Description

Param

Parameter

DisplayName

User friendly display name of the parameter to be shown in the GUI. Some of the Application parameters may have cryptic names.

Default

Default value of the parameter.

Description

Description of the parameter. This will be shown along with the parameter in GUI

ValueType

This element defines datatype, validation rules and mapping rules for Enumerations. This element contains different elements and attributes based on value of the Type attribute. Refer below table for details

Type

Data type of the parameter. Below are supported values

Enumeration: Predefined set of values

Example: For a Parameter Day the values can be one of the fixed values

Mon, Tue, Wed, Thu, Fri, Sat, Sun

Numeric: Integer data types.

String: Alphanumeric character types

Date: Date type

For ValueType > Type = Enumeration

Enumeration

Define all possible valid Parameter values and corresponding user friendly name to be shown in the GUI

EnumIndex

Value of the Parameter to be shown in the GUI

EnumValue

Value of the Parameter to be stored in an Application Parameter file. Parameter file gets downloaded to the Device. Application on Device uses this Parameter value.

Example:

Enable Tip parameter can have values 0 or 1

0 means Tip is Enabled , 1 means Tip is Disabled

GUI will show options to the user to select either Disable or Enable.

The default value is defined in the PDX file for each parameter.

For ValueType > Type = String

MinLen

Minimum length of the parameter value.

MaxLen

Maximum length of the parameter value.

ValidChars

Valid characters allowed as part of the parameter value.

You need to specify a regular expression to define set of valid characters allowed as part of the parameter value.

ErrorOnValidationFailure

Error to be shown in case user has specified invalid value.

This should be a generic message that indicates all the allowed valid characters.

For ValueType > Type = Numeric

MinVal

Minimum allowed value of the parameter.

MaxVal

Maximum allowed value of the parameter.

For ValueType > Type = DateTime

DateFormat

Format of date value. Example MM/DD/YYYY HH:MI:SS

[TBD:JS] Validate this with Srinivas.

Need to list all the valid options like

MM – Month, DD – Day etc.

 

Parameter Templates

Parameter Templates provide you a convenient way to manage a common set of parameters that apply to a group of devices.
EXAMPLE: TCPIP Communication parameters for a group of devices in a Store (or a region) may be common. Instead of configuring these parameters for each device, you can define a Parameter Template that defines values for all the TCPIP Communication parameters and assign it to required devices.
You can change the values of these parameters for a Parameter Template and same get applied to all the associated devices.The parameter templates, define values for some or all the parameters of an application. You can configure one or more parameter templates for each application.To configure parameter templates for an application:To configure parameter templates, ensure that you have configured PFX for this application.Go to Device Management > Manage Downloads > Applications Library. The Application Library screen is displayed.Click the Configure link under Parameter Templates column on the selection application. The Parameter Templates screen lists the parameter template and their description. 

Adding Parameter Template

You can configure one or more parameter templates for an application in the Parameter Templates for Application screen.To add a parameter template to an application:On the Parameter Template screen, click (Add Parameter Template) to add a parameter template in for application. The Add Parameter Template screen is displayed.Enter the value, Parameter Template Name and add Description to the template.Click (Restore to Default) to restore the parameter to the default value.Click Add. The Parameter Template is added to the application successfully.

Editing Parameter Template

You can edit the parameter template.To edit the parameter template of an application:Select the parameter template assigned to an application.Click (Edit Parameter Template) to edit the parameter value.Click Save to apply the changes. The Parameter Template changes are successfully saved.

Deleting Parameter Template

You can delete the parameter template.To delete the parameter template of an application:Select the Parameter Template.Click (Delete Parameter Templates). The Confirmation message box is displayed. Click Yes to delete the parameter template and click No to close the confirmation message
box.

Copying Parameter Template from other Application Version

You must select the parameter template assigned to an application.Click (Copy from other versions).This feature copies the parameter template from other versions of an application.You can view all the parameter templates, application version from where the parameter template is copied, the parameter template modified date and time and the modifications made by.Click Save to apply the changes.

Parameters for Single Device

You can configure parameters for single device from its Device Profile.To configure application parameters: Go to Device Search and search for the device.Click on serial number in Serial# column to view the Device Profile information.On the Device Profile, click Device Details > Parameter.The screen shows all the applications ­assigned to the selected device. You can configure Parameters of the Application by editing the Parameter values and assigning the Parameter Templates.Based on the information in form view file the Basic Parameter and Advance Parameter editing with the access control options such as Advanced, Basic, View, and None are provided for the user.The access control operates both at the Container level and the parameter level. However, the access control of the Container level always takes precedence.The sample form view XML file with the access control is displayed below:The roles are assigned to the level of access. The below table lists the access, rights and the privileges provided to the user.
Form File Container/Parameter Level Access VHQ Rights UI Parameter Edit Option Allowed
Basic Parameters [Modify] Advanced Parameters [Modify]
Basic TRUE TRUE TRUE
TRUE FALSE TRUE
FALSE TRUE TRUE
FALSE FALSE FALSE
Advanced TRUE TRUE TRUE
TRUE FALSE FALSE
FALSE TRUE TRUE
FALSE FALSE FALSE
None NA NA NA
View NA NA FALSE
Form File Container/Parameter Level Access VHQ Rights UI Parameter View Option Allowed
Basic Parameters [View] Advanced Parameters [View]
Basic TRUE TRUE TRUE
TRUE FALSE TRUE
FALSE TRUE TRUE
FALSE FALSE FALSE
Advanced TRUE TRUE TRUE
TRUE FALSE FALSE
FALSE TRUE TRUE
FALSE FALSE FALSE
None NA NA FALSE
View NA NA TRUE
VHQ provides the user with separate rights and privileges to edit parameters rather than editing them with the Device rights.
EXAMPLE: Currently, the user, with the Basic Parameter right and Advanced Parameter rights can edit the parameters of a single device from the Device profile.

Parameters for Single Device

You can configure parameters for single device from its Device Profile.To configure application parameters: Go to Device Search and search for the device.Click on serial number in Serial# column to view the Device Profile information.On the Device Profile, click Device Details > Parameter.The screen shows all the applications ­assigned to the selected device. You can configure Parameters of the Application by editing the Parameter values and assigning the Parameter Templates.Based on the information in form view file the Basic Parameter and Advance Parameter editing with the access control options such as Advanced, Basic, View, and None are provided for the user.The access control operates both at the Container level and the parameter level. However, the access control of the Container level always takes precedence.The sample form view XML file with the access control is displayed below:The roles are assigned to the level of access. The below table lists the access, rights and the privileges provided to the user.
Form File Container/Parameter Level Access VHQ Rights UI Parameter Edit Option Allowed
Basic Parameters [Modify] Advanced Parameters [Modify]
Basic TRUE TRUE TRUE
TRUE FALSE TRUE
FALSE TRUE TRUE
FALSE FALSE FALSE
Advanced TRUE TRUE TRUE
TRUE FALSE FALSE
FALSE TRUE TRUE
FALSE FALSE FALSE
None NA NA NA
View NA NA FALSE
Form File Container/Parameter Level Access VHQ Rights UI Parameter View Option Allowed
Basic Parameters [View] Advanced Parameters [View]
Basic TRUE TRUE TRUE
TRUE FALSE TRUE
FALSE TRUE TRUE
FALSE FALSE FALSE
Advanced TRUE TRUE TRUE
TRUE FALSE FALSE
FALSE TRUE TRUE
FALSE FALSE FALSE
None NA NA FALSE
View NA NA TRUE
VHQ provides the user with separate rights and privileges to edit parameters rather than editing them with the Device rights.
EXAMPLE: Currently, the user, with the Basic Parameter right and Advanced Parameter rights can edit the parameters of a single device from the Device profile.
With Basic and Advanced Parameter rights, Import Parameter and Activation Parameter rights are added in VHQ.Import Parameter Right: User with the assigned Import right can import devices and hierarchy in VHQ. VHQ checks for the Device right during import process. Based on the operations specified in import XML, VHQ checks for the rights of the user before performing the operations.Activation Parameter Right: User with the assigned Activation right can activate parameters in VHQ. The user must have Device modify right with the Activation right. With the Device right the user is only able to update or edit the parameters in UI but will not be able to send the parameters to device. In order to send the parameters to the device or activate the parameters, the user must have the Activation Parameter rights.VHQ provides right and privilege to perform global operations from VHQ GUI that involves more than one device. All the global operations in Device Search screen should be restricted based on this right.Following is the list of Global operations in Device Search screen where more than one device is involved. Global Right works on top of existing rights for specific operations.
Screen Actions Existing Rights
Device Search- Status Active Devices – Modify
Inactive Devices – Modify
Pending Administration Devices – Modify
Device Search - Actions Blacklist Devices – Delete
Delete Devices – Delete
Export to XML Devices – Delete
Device Search - Schedule Content Content Schedule - ModifyDevice - ViewContent library - View
Diagnostic Actions Diagnostic Actions - ModifyDevice - View
Downloads Download Schedule - Modify Device - ViewDownload library - View
Device Search -Edit Hierarchy Edit Hierarchy Devices - Modify
Device Search -Group Add Group Assignment Devices - Modify
Delete Group Assignment Devices - Modify
Device Search-Parameters Edit Parameters Devices - Modify
Device Search -Software Software Assignment Device View and Download Schedule - Modify
Software Upgrade Device View and Download Schedule - Modify
Schedule Downloads Schedule Download Schedule - Modify Download library - ViewDevice – View
Diagnostics Schedule Actions Diagnostic Actions - ViewDevice - ViewDiagnostics – ModifyReports & charts - View
Schedule Content Schedule Content Schedule - ViewContent Library – ViewContent Schedule - Modify

Edit Parameters

You can edit the parameters.To edit the parameters:To configure Parameter Templates, ensure that you have configured PFX for this Application.Go to Device Profile screen.Click to edit parameter.On the Edit Parameter for Application form window, select the value from the drop-down list. The Containers are listed as tabs and the parameters are displayed with the relevant values. The full screen view and the tooltip features make it easy for the users to view the description with the validation rule or edit the parameters.Click to edit the parameters. On the pop-up screen, enter the values. You can either restore the parameter definition file default values or the template value. Click Save to apply the changes.On Device Profile screen, click Activate to send parameters automatically to the device.
NOTE: Based on the Direct Parameter Activation under Estate Administration > System Configuration > System you can set the configuration value of the Direct Parameter Activation to True or False to decide if parameters are to be sent automatically on modification or not. If set to True, the Activate button will not be visible on the Device Profile, Parameter tab. If set to False, the Activate button will be visible at the Device Profile, Parameter tab.
If the Direct Parameter Activation configuration is set to True, the Activate button in Device Profile > Parameter tab is hidden.If the Direct Parameter Activation configuration is set to False, the Activate button will be visible in Device Profile screen to activate the parameters.
NOTE: All the parameters defined in PFX will be shown in this list. In case you do not want to show specific Parameters for editing in this list, you can exclude the same from PFX. Default values will be set for such Parameters.
You can configure appropriate values for the Parameters.If you do not configure any value to a Parameter, the Parameter will be set to its default value (as defined in PDX). By default, the list shows all parameters with their default values (as defined in PDX).
NOTES:How VHQ evaluates the Parameters that are downloaded to the Device? VHQ builds and downloads the parameters with the values in the below order of precedence:Parameter values configured at the Device Level.Parameter values configured for Parameter Templates.Default Parameter values as defined in PDX. Parameter values configured for a Device take highest precedence. If not configured for the device. Parameter values configured for Parameter Templates will be considered. For the parameters not configured for Device and PT, the default values as defined in PDX will be set, configured for Device and PT, the default values as defined in PDX will be set.

Edit Template Assignment

You can edit template assignment.To edit template assignment:Go to Device Profile screen.Click Edit Template Assignment.The screen lists the template (s) available for the selected devices. Click to assign the parameter template. You can assign multiple parameter templates and order them to set the parameter precedence.Click Save to apply the changes.Click to reset the values.Click View link to view the parameters and their default values in the containers.Click to restore default values.

Configuring Parameter at Device Search (Multiple Devices)

You can configure parameters for multiple devices from Device Search.To configure parameter for multiple devices:Select the multiple check boxes in Device Search. The Actions window is displayed.Click Parameters > Activate Parameters to activate parameters for the selected devices. On performing this action, a confirmation message is displayed on the screen. Click Yes to proceed and No to cancel the operation.
NOTE: Parameters will be activated for the Devices which have Applications with Parameter Form View File.
Click Edit Parameter to edit parameter of any particular device. You can only edit parameter of a single device.
NOTE: The applications listed for the particular devices can also be a part of other devices. However, editing parameters of these applications of a particular device will not affect the parameters of the applications of other devices.
On the Edit Parameters for Application screen, you can:
  • Edit Template Assignment
  • Edit Parameters
  • Activate
  • Restore All to Template

Edit Parameters

To configure Parameters, ensure that you have configured PFX for this Application. The list of all the Application Parameters and their values can be viewed. By default, the list shows all parameters with their default values (as defined in PDX). All the parameters defined in PFX will be shown in this list. In case you do not want to show specific Parameters for editing in this list, you can exclude the same from PFX. Default values will be set for such Parameters. You can edit the parameters.Parameters Sync Status indicates if the parameters configured on VHQ are synchronized with the parameters on the device.The Parameters Sync Status is:
  • Not in Sync: If the changes to parameters after editing on VHQ are not yet downloaded to the device.
  • In Sync: If all the changes to parameters after editing on VHQ are downloaded to the device.
Click on the Status icon to see detailed status.

Edit Template Assignment

You can edit template assignment.To edit template assignment:
  1. Go to Device Profile screen.
  2. Click Edit Template Assignment. The screen lists the common templates available for the selected devices.
  3. Select the available parameter template.
  4. Click View link to view the parameters and their default values.
  5. Click to assign the parameter template. You can assign multiple parameter templates and order them to set the parameter precedence.
  6. Select the Overwrite existing assignment to delete the existing parameter template and add the selected parameter template to the common application of the particular device.
  7. Click Save to apply the changes.

Parameter Synchronization (Download) to Devices

The Downloads or Synchronize phase involves evaluating and building the list of parameters that is to be downloaded in the appropriate format and download. The system checks for the parameters at the device level and configures at VHQ Server. The system evaluates the listed parameters and matches for the values. If the matching criteria are matched, the synchronization takes place.If the synchronization fails, the system prepares the package, bundles the applications, Parameter Form File, Parameter Templates and is sent to the device with appropriate GID.Once the user has configured the Parameters and Saved (or Activated) the changes, VHQ evaluates, builds and downloads a Parameter file – that contains the Parameters and their values in appropriate format (based on Parameter Definition file).
NOTE: VHQ supports parameter downloads only through Automated downloads.

Evaluate the Parameters and their values

VHQ builds and downloads the parameters with the values in the below order of precedence.Parameter values configured at the Device Level.Parameter values configured for Parameter Templates.Default Parameter values as defined in PDX.Parameter values configured for a Device take highest precedence. If not configured for the Device, Parameter values configured for Parameter Templates will be considered.For the parameters not configured for Device and PT, the Default values defined in PDX will be set.

Identify the Parameter change set

As part of Automated downloads, VHQ detects if a software update is required for a device and sends the required Download Instructions (known as Management Plan) to the device. The Device then, downloads the required updates.Along with every Software update, VHQ sends the required Download Instructions to download all the parameters of the all the applications contained in the Software update.The device sends a confirmation indicating that parameters were successfully downloaded and applied to the device. VHQ records this date and time as Synchronized Date.After sometime, VHQ user configures/edits the parameters for the device and saves (or Activates) the changes. VHQ records this as Activation Date.VHQ identifies the list of parameters that have Activation Date higher than Synchronized Date – as changed parameters.

Build the Parameter File

VHQ builds a Parameter file to download to the device. Parameter file may contain only changed parameters or all the parameters based on the capability of the Application/OS on device to consume the Parameter file.The format and content (all or only changed Parameters) of the Parameter file are determined by the value of Parameter File > Format in Parameter Definition File. Parameter files with Config.sys and Config.$$$ format is compressed as a .ZIP file. .ZIP file will have one folder per GID with Folder name set as the value of GID.Parameter files with ADKH format are built based on the format structure provided in Parameter File > OutFileFormat section.The parameters can be downloaded to the device in different formats. The format in which the parameters can be downloaded is mentioned in PDX file. The different format to which it can be downloaded are POINT, ADKH, CONFIG$$$ and CONFIGSYS.

Download and Verify

VHQ prepares the Download instructions to download Parameter files.In case a Package has 2 Applications and each Application has 2 Parameter files, the Management Plan will contain instructions to download:Software Package.Parameter File#1 for Application#1, Parameter File#2 for Application#1.Parameter File#1 for Application#2, Parameter File#2 for Application#2.VHQ sends the Download Instructions to the device.Device processes the Download Instructions to download each of the files. The device applies the Parameters and sends the status information.VHQ receives the status and updates the synchronization status.User can see the Parameter Synchronization status for each Application on Device and also the detailed Synchronization status for each Parameter File.

Parameter Download support for Reference Set Assignment

This feature is enhanced to support downloading of parameters to the devices where the Assignment Type is Reference Set. The Reference Set is either assigned directly to a device or inherited from the Hierarchy.The Device Profile screen displays the Reference Set Name assigned to the device. With the Reference Set assignment, the users are able to edit the parameters in the Device Profile screen.
NOTES:No Parameter Upgrade support is provided for the Parameters inherited through Reference sets.No Parameter Template support is provided at RS level.

Managing COO (Change of Ownership) Parameters

There are two major enhancements with respect to the Change of Ownership of Parameters.Import ModuleDevice Callback FeatureImport Module: This feature auto imports the device details available in .xml or .csv file from a pre-defined folder location instead of manually importing the files from VHQ GUI.The following changes must be made to the .xml import file.Version of .xml file is set to 2.0Hierarchy Section: Rename to HierarchyName.Group Section: Rename to GroupName.Device Section:Hierarchy tag rename to HierarchyPath.HierarchyName is added.Operation and Upgradable Package are added under Package assignment section.Operation tag in Package Assignment section specifies Assign/Unassign/Upgrade the package. The possible values for Operation are A/D/U. (add/delete/modify)Upgradable Package to be upgraded.If value of HierarchyPath is blank, the Import tool uses the value given in the HierarchyName attribute to place the device in the appropriate node in the VHQ hierarchy.The operation fails, if there are multiple nodes in the VHQ hierarchy with the same hierarchy node name.In Update (U) operation for a device, status of device can be updated to Inactive or Deleted.If the device status is set as Inactive or Deleted:Software Assignment and Software Upgrade will fail.The Parameters assigned to the applications cannot be updated.VHQ Import tool generates an Import Status XML output file with the following information about the processing status of the device records in the XML input file:The XML import status file generated on a pre-defined location, with the name <Import_File_Name>_<VHQVHQ user ID of user who initiated the import>_YYYYMMDDHH24MISS.xml, and the status file is accessible from VHQ GUI.Summary ResultsThe summary results include the following information:Total number of device records in XML input file.The number of device records that were successfully processed from XML input file.The number of device records that were rejected from XML input file, along with a breakdown of the error count for each type of error code reported in the output status file.Detailed ResultsFor each of the records that were rejected from the input file, the output status XML file includes the following information:A dump of the device record from the input file.An error code with a descriptive message indicating the reason why the device record was NOT processed by VHQ import tool.The table given below has a list of suggested error codes that VHQ import tool can return when processing a record in the XML input file.
Error Code Description
E_DUPLICATE_TERMINAL Specified device already exists
E_INVALID_HIERARCHY Hierarchy does not exist.
E_DUPLICATE_HIERARCHY Multiple nodes found in hierarchy for value of “HierarchyName”.
E_INVALID_APPLICATION Application does not exist
E_INVALID_MODEL Model does not exist
E_INVALID_PACKAGE Package does not exist
E_INCOMPATIBLE_PACKAGE Package is not compatible with existing packages assigned to device, due to presence of common application.
E_INVALID_PARAMETER Parameter does not exist
E_INVALID_REFERENCE_SET Reference set does not exist
E_INVALID_GROUP Group does not exist
E_LICENSE_EXCEEDED Unable to add device, as the number of devices currently in the VHQ database has exceeded the licensed number of devices.
E_GENERAL_ERROR General Error
The Sample XML file format is given below:The Sample Result XML file format is given below:

Managing Parameters with Associated Rights

In VHQ, Parameters rights restricts a user in viewing or editing the parameters based on the access level. The user is restricted or allowed to access to any parameter, on the access level defined in the Parameter Form file. These restrictions are of great help in hiding or showing the parameters for the specific users.With the current implementation, the user can not only hide or show the parameters or edit the parameters, but can also restrict the value of the parameter, even if the user has a right to view the parameter.
NOTE: If a parameter value is a password of some sort, other users will not be able to see the password, even though they have access to view or edit the parameter.
In order to meet the requirement of the user, a new attribute “MaskValue” is introduced next to “Access” attribute in VPFX XML. Masking is an act of applying a mask to the value. If the “MaskValue” attribute is set to ‘true’ (case insensitive) then the parameter value is masked with asterisks (*****), else if set to “false” the value is unmasked.The user with add permission will be able to define and add value to the defined parameter irrespective of the value being masked. The user with modify permission will be able to edit the parameter value and can also restore the parameter value to default. However, the modified value cannot be seen, since that is the expected behaviour of MaskValue. The user cannot delete the parameters.
NOTES: The user must not be able to copy the value.Masking is only applied to the parameters whose value type is String.If the MaskValue attribute is not set to true or false (Boolean value) in the form view xml file, then by default the attribute is unmasked and the user is not allowed to upload the form file. The following error as “Invalid file format” is displayed.
Multi-Merchant and Card Range Parameter ManagementMultiMultiVHQ offers support for Multi-Merchant and editing of Card Range parameter management for all the VHQ managed devices. The multi merchant functionality allows several merchants to share a single device, making it easier for the merchants to configure, edit, download and manage the values of the application parameters. The device owner creates the merchant IDs to be accessed by the individual merchant. The merchant then logs in to the device with the credentials and perform a transaction, which gets recorded into the system.VHQ supports Multi-Merchant functionality by reusing the same set of parameters and creating multiple instances with different parameter values.With the existing functionality, VHQ manages parameters for applications at container levels, where the parameters were mapped to a single instance. However, with the introduction to Multi-Merchant functionality, VHQ supports handling of parameters for the applications multi-instance and multi-level.Multi-Level: Multiple child levels for the Parent. Hierarchal levels of parent child relationship.Multi-Instance: A set of parameters which are repeated for the same level with different values.As part of the VHQ Multi-Merchant parameter management process flow, the application developers build a parameter definition file (.vpdx) that defines all parameters of the application and their attributes and multiple form files (.vpfx) for editing application parameters.
NOTE:A hair salon could get a device that serves up to 20 different merchants, so each stylist/contractor/merchant would function as an individual by logging into the same device with the provided credentials and perform the transaction.
In most cases the multi merchant devices, download the parameters once per business day (or more often) and next-day funding options offer cash-flow opportunities that were previously unattainable. If any parameter is edited or new instances are added, the parameter download happens.
NOTE:Parameter editing and viewing is allowed only if application is configured with form file or when the form file is uploaded.

Editing Parameter for Multi-Merchant

Editing parameters for Multi-Merchant and card ranges across all VHQ devices can be done by:
  • Importing an XML File
  • VHQ GUI

Editing Parameters for Multi-Merchant - Importing an XML File

You can add or modify instances or merchants through xml file. These xml files are prepared by Customer Administrators, Regional Support representatives or VHQ Support personnel.To import an xml file:Go to Device Management > Add Devices.Select Add Device via File Import.Browse for the xml file and click Import. The import file is successfully processed.

Editing Parameters for Multi-Merchant - VHQ GUI

To edit parameters from the GUI, the user must upload the .vpdx and .vpfx file.You must do the following:You must check for the container level “MultiInstance” attribute set to “Yes” in .vpdx file
<Container Name="Merchant" MultiInstance="Yes" OutFilePrefix = "adk">
You can upload multiple levels of .vpfx file to the application assigned to the device. However, you must check for the parent ID attribute, which must be present in while uploading vpfx file.AllowAdd, AllowDelete, AllowEdit when set to True, allows the user to create, delete and edit instance.AllowSequnece when set to True, allows the user to set the ordering for the merchant. On deletion of any merchant(s) the preceding merchant will take the sequence order.
<vhq:ParameterElements xmlns:vhq="http://www.verifone.com/VHQ/Parameter/schema" version="2.0" Name="Currency" Parent="General" AllowAdd ="True" AllowDelete="True" AllowEdit="True" AllowSequence="True">
On uploading the vpdx and vpfx file, assign the application to the device. For more information on assigning application to the device, refer Software Assignment. Once uploaded you can edit parameters in the GUI and create instances or merchants.To edit parameter:Select a device or search for a deviceOn the Device Profile screen, click Device Details > Parameter tab.Click to edit the parameters.On Edit Parameter for Application window, click on the merchant node to view the list of merchants configured. You can also add new merchant, edit merchant specific parameters and delete an existing merchant. The merchant is identified by Merchant Id and Name.You can also add a merchant.To add a merchant:On the Edit Parameter for Application window, click .Enter the Merchant ID, Merchant Name, Address and other necessary details in the fields. You can also restore the default value.Click Save.Click Add. The new instance is added to the application successfully.You can also edit a merchant.To edit a merchant:Select the merchant and click .Edit the value and click Save.You can also delete a merchant.To delete a merchant:Select the merchant and click .Edit the value and click Save.Click to set the order of merchant sequence. You can manage multiple levels in the Edit parameter for application screen.On creation or modification of the merchant the parameters are downloaded to the device.

 

Editing the parameters in Device Profile

Learn how to edit the parameters in Device Profile screen.

 With Basic and Advanced Parameter rights, VHQ supports Import Parameter and Activation Parameter rights:

  • Import Parameter Right: User with the assigned Import right can import devices and hierarchy in VHQ. VHQ checks for the Device right during import process. Based on the operations specified in import XML, VHQ checks for the rights of the user before performing the operations.
  • Activation Parameter Right: User with the assigned Activation right can activate parameters in VHQ. The user must have Device modify right with the Activation right. With the Device right the user is only able to update or edit the parameters in UI but will not be able to send the parameters to device. In order to send the parameters to the device or activate the parameters, the user must have the Activation Parameter rights.

VHQ provides right and privilege to perform global operations from VHQ GUI that involves more than one device. All the global operations in Device Search screen should be restricted based on this right.

Following is the list of Global operations in Device Search screen where more than one device is involved. Global Right works on top of existing rights for specific operations.

Screen

Actions

Existing Rights

Device Search- Status

Active

Devices – Modify

Inactive

Devices – Modify

Pending Administration

Devices – Modify

Device Search - Actions

Blacklist

Devices – Delete

Delete

Devices – Delete

Export to XML

Devices – Delete

Device Search - Schedule

Content

Content Schedule - Modify

Device - View

Content library - View

Diagnostic Actions

Diagnostic Actions - Modify

Device - View

Downloads

Download Schedule - Modify Device - View

Download library - View

Device Search -Edit Hierarchy

Edit Hierarchy

Devices - Modify

Device Search -Group

Add Group Assignment

Devices - Modify

Delete Group Assignment

Devices - Modify

Device Search-Parameters

Edit Parameters

Devices - Modify

Device Search -Software

Software Assignment

Device View and Download Schedule - Modify

Software Upgrade

Device View and Download Schedule - Modify

Schedule Downloads

Schedule

Download Schedule - Modify Download library - View

Device – View

Diagnostics

Schedule Actions

Diagnostic Actions - View

Device - View

Diagnostics – Modify

Reports & charts - View

Schedule Content

Schedule

Content Schedule - View

Content Library – View

Content Schedule - Modify

Edit Parameters

You can edit the parameters.

To edit the parameters:

To configure Parameter Templates, ensure that you have configured PFX for this Application.

  1. Go to Device Profile screen.
  2. Click to edit parameter.

On the Edit Parameter for Application form window, select the value from the drop-down list. The Containers are listed as tabs and the parameters are displayed with the relevant values. The full screen view and the tooltip features make it easy for the users to view the description with the validation rule or edit the parameters.

  1. Click to edit the parameters. On the pop-up screen, enter the values. You can either restore the parameter definition file default values or the template value. Click Save to apply the changes.
  2. On Device Profile screen, click Activate to send parameters automatically to the device.

NOTE: Based on the Direct Parameter Activation under Estate Administration > System Configuration > System you can set the configuration value of the Direct Parameter Activation to True or False to decide if parameters are to be sent automatically on modification or not. If set to True, the Activate button will not be visible on the Device Profile, Parameter tab. If set to False, the Activate button will be visible at the Device Profile, Parameter tab.

  • If the Direct Parameter Activation configuration is set to True, the Activate button in Device Profile > Parameter tab is hidden.
  1. If the Direct Parameter Activation configuration is set to False, the Activate button will be visible in Device Profile screen to activate the parameters.

NOTE: All the parameters defined in PFX will be shown in this list. In case you do not want to show specific Parameters for editing in this list, you can exclude the same from PFX. Default values will be set for such Parameters.

You can configure appropriate values for the Parameters.

If you do not configure any value to a Parameter, the Parameter will be set to its default value (as defined in PDX). By default, the list shows all parameters with their default values (as defined in PDX).

NOTE:  Refer to the How does VHQ evaluates the parameters that are downloaded to the Device?   section to know more about how VHQ evaluates the parameters that are downloaded to the Device.

Edit Template Assignment

You can edit template assignment.

To edit template assignment:

  1. Go to Device Profile screen.
  2. Click Edit Template Assignment.

The screen lists the template (s) available for the selected devices. Click to assign the parameter template. You can assign multiple parameter templates and order them to set the parameter precedence.

  1. Click Save to apply the changes.
  2. Click to reset the values.
  3. Click View link to view the parameters and their default values in the containers.
  4. Click to restore default values.

How does VHQ evaluate the parameters that are downloaded to the Device?

Learn about how VHQ evaluates the parameters that are downloaded to the device.

 Following are the steps that explains how VHQ evaluates the parameters that are downloaded to the device.

  1. VHQ builds and downloads the parameters with the values in the below order of precedence:
  2. Parameter values configured at the Device Level.
  3. Parameter values configured for Parameter Templates.
  4. Default Parameter values as defined in PDX. 
  5. Parameter values configured for a Device take highest precedence. If not configured for the device. Parameter values configured for Parameter Templates will be considered. For the parameters not configured for Device and PT, the default values as defined in PDX will be set, configured for Device and PT, the default values as defined in PDX will be set.