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:
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.
Setup/definition phase that involves setting up all pre-requisite configurations to enable Parameter Management.
Configuration phase that involves identifying the Parameters (and their values) that need to managed for specific devices. It includes:
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:
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.
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:
For more details about the Parameter Definition File, refer to the Parameter Form File section.
To configure parameter definitions for application:
NOTE: The Parameter Definition File can only be uploaded once.(Current Implementation)
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.
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:
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:
None: Indicates no parameter form view file is selected.
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.
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 |
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. |
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.
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 |
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.
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 |
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 |
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.
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:
NOTE: VHQ supports parameter downloads only through Automated downloads.
NOTES:No Parameter Upgrade support is provided for the Parameters inherited through Reference sets.No Parameter Template support is provided at RS level.
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 |
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.
<Container Name="Merchant" MultiInstance="Yes" OutFilePrefix = "adk"> |
<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"> |
With Basic and Advanced Parameter rights, VHQ supports Import Parameter and 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 |
You can edit the parameters.
To edit the parameters:
To configure Parameter Templates, ensure that you have configured PFX for this Application.
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.
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.
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.
You can edit template assignment.
To 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.
Following are the steps that explains how VHQ evaluates the parameters that are downloaded to the device.