Vynamic™ View ProAgent JRE 5.3.

3
Operation Manual
Version 1.0, 16.4.2020
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2. Overview of ProAgent (JRE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3. Network requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3.1. Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. New folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
6. Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1. Start ProAgent (JRE) service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.2. Stop ProAgent (JRE) service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.3. Check the status of ProAgent (JRE) service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1. Property File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.2. General parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.3. Service related parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
7.3.1. Local services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
7.3.2. Remote services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.4. Communication lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.4.1. Multiple server communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.4.1.1. Enabling the multiple server communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.4.1.2. Example configuration for multiple servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.5. Secure TCP/IP connections using TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.6. Must match server certificate. Optional - does not have to be used. . . . . 17
7.7. Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.8. Example log4J.properties file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.9. Change the name of the terminalID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.10. Service wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8. Event and Command Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.1. Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.1.1. Standard Event Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.1.2. Standard Command Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.1.3. General configuration rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
 8.2. File Transfer Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.2.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.2.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.3. Heartbeat Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.3.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.3.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8.3.3. Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8.4. Send Check Command Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8.4.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.4.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.5. System Provider ........................................................... 25
8.5.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.5.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.5.3. Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.6. Text File Provider .......................................................... 26
8.6.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.6.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.6.3. Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.7. FDM Event Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.7.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.7.2. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.7.3. Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9. Event Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.1. Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2. Event Filter Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.1. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.2. Identifying events by their contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.3. Identifying events by their number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.4. Syntax of regular expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.5. Example of a filter configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.3. Event Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.3.2. Subscriber Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.3.3. Event Log Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
9.3.3.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
9.3.3.2. Specific configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
9.3.4. ActiveMQ subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
9.3.4.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
9.3.4.2. Specific configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
9.3.5. Command Execution Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.3.5.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.3.5.2. Specific configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
 Preface

Trademark Rights
Almost all hardware and software names contained in this document are also registered trademarks
of their respective product owners and should be treated as such. Diebold Nixdorf has, in the main,
followed the manufacturers' spelling for product names.

Confidentiality Undertaking
Copyright © Diebold Nixdorf, Inc. (2019) – All rights reserved - The contents of this document may
not be reproduced, exploited or published, whether in whole or in part, without the prior written
permission of Diebold Nixdorf. This also includes translation into other languages. The copyright
applies to all forms of storage and reproduction in which this information is incorporated including,
but not limited to, magnetic memory, computer printouts and visual displays. Offenders will be liable
for damages.

All rights, including rights created by patent grant or registration of a utility model or design, are
reserved. Right of technical modifications reserved.

Names and Other Data

The names, e-mail addresses, telephone numbers and other data used in this document are purely
fictional (except the e-mail addresses listed below to return feedback to this document). Any
resemblance to actual persons, living or dead, is coincidental.

Technical Support
In case of questions or problems related to all Diebold Nixdorf Software products you should open a
ticket via iSupport: https://ebusiness.wincor-nixdorf.com/OA_HTML/iSupportLogin.jsp

If you do not have access to iSupport, then please use the live chat to contact a DN Help desk for
immediate assistance (https://diebold.learn.taleo.net).

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 1

1.1. About this document

1. Introduction
Vynamic™ View (formerly named ProView) is a part of Diebold Nixdorf’s
Vynamic™ Software. In version 5.1, the product was rebranded to reflect the new
 name Vynamic™ View and also the corporate Vynamic™ Design. In some
technical parts such as server path names, registry or file names, ProView stays.
In the version 5.0 and prior, the product is still named as ProView.

1.1. About this document

This document gives a detailed description of the functionality, installation, and configuration of the
ProAgent (JRE).
It provides information required to understand how to install, configure and operate the ProAgent
(JRE). A description of the filter mechanism for events and an example configuration is provided.
The manual is targeted at administrators of devices to be monitored with ProAgent (JRE).

In addition to system administration, know-how knowledge about the Linux operation system and
about the network is required (network administrator).

1.2. Overview of ProAgent (JRE)

The ProAgent (JRE) is the monitoring component on the device. It sends events to a sender, executes
commands and transfers files from and to a server. It communicates with the Vynamic™ View Server
and connected devices via defined interfaces.

2 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 2.1. Hardware requirements

2. Prerequisites
Before installing ProAgent (JRE), you need to check if hardware and software resources meet the
minimum requirements.

2.1. Hardware requirements

Minimum memory 1 GB
Minimum disc 400 MB
Minimum processor 1 CPU
Network interface card installed and enabled

Table 1. Minimum hardware requirements

2.2. Software
The following table lists the software requirements.

Operating system Java version

CentOS 7.5 (64-bit) OpenJDK 8
OpenSUSE 42.1 Oracle JRE 8

Table 2. Software requirements

2.3. Network requirements

Since the ProAgent (JRE) communicates with a server (a Vynamic™ View Server, a Vynamic™ View
Gateway or another management system), certain network requirements need to be fulfilled.

2.3.1. Firewall
Most networks today are secured by one or more firewalls. If at least one of the affected components
– server, ProAgent (JRE), devices, etc. is on the other side of the firewall, two open ports are required.
One for listening to incoming calls, and the other one for sending and receiving messages.

SSOP The default listening port in Vynamic™ View Server is port 18988. The default
message handling port on ProAgent (JRE) is 18988. You need to set up your firewall
to open these ports in order to enable communication via SSOP.

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 3

3. Installation

3. Installation
There has been prepared an RPM package for the installation and uninstallation of the ProAgent
(JRE).

The installation has to be done with root permissions. In the examples in this document, the sudo
command is used to elevate the privileges.

Installation folder

 The ProAgent (JRE) will be installed into /opt/JAgent, this folder is in this
document further referenced as <Agent (JRE) folder>.

The command to install the package is the following (using the RPM file that you can find on the
installation CD of Vynamic™ View):

sudo rpm -iv JAgent-XXYY-Z.rpm

(Where XXYY is the version of the ProAgent (JRE) and Z is the release number)

FOLLOWING STEPS WILL BE DONE DURING THE INSTALLATION:

• If group “jagent” doesn’t exist, it is created

• If user “jagent” doesn’t exist, it is created
• Copying all files needed to <Agent (JRE) folder>
• Setting the default values for the configuration files (see how to configure the ProAgent (JRE) in
the Configuration)
• It will install the ProAgent (JRE) service for jagent user

The user “jagent”

When the user “jagent” is created, it will be created without password (it will be not
possible to login with jagent) and the home directory for this user will be created in

 /opt/JAgent/tmp.

In order to prevent possible issues due to the specific requirements on home

directory and password of the “jagent:” user created by ProAgent (JRE), it is highly
recommended not to create the user “jagent” manually before the installation.

Open SUSE installation

 Before starting the “JAgent” service on Open SUSE, it is recommended to either

restart the systemd using the sudo systemctl daemon-reexec command, or reboot
the machine. The “JAgent” service might otherwise not be able to start.

4 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 3.1. New folders

Set the correct configuration for a new installation

Because the configuration files have been filled with a default configuration values,
you have to set the correct values to these files (see how to do that in the
Configuration of the ProAgent (JRE)). Especially, you have to correct the value of

 the key "AGMGR01_RemoteHost"

folder>/conf/pvagent.properties.
in the file <Agent (JRE)

If there is a backup configuration file (<Agent (JRE)

folder>/conf/pvagent.properties.rpmsave, refer to the hint in Uninstallation), the
AGMGR01_RemoteHost value will be restored.

3.1. New folders

On the destination system, the installation procedure generates the following subfolders under the
installation folder:

• lib (It belongs to root: root)

This folder contains the libraries needed to run the ProAgent (JRE).
• data (it belongs to jagent: jagent)
This folder contains the log files (inside data/trace) and the events stored to be sent (inside
data/eventstore)
• conf (it belongs to jagent: jagent)
This folder contains all configuration files needed for the configuration of the ProAgent (JRE)
• bin (it belongs to root:root)
This folder contains the scripts and executable files needed for the working of the ProAgent (JRE)
• tmp (it belongs to jagent: jagent)
Temporary folder used internally. Also, if the user “jagent” is created during the installation, this
will be his home folder.
• templates (it too belongs to root:root)
Folder with templates used by the service

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 5

4. Update

4. Update
To update the ProAgent (JRE) you have to execute the following command:

sudo rpm -Uvh JAgent-XXYY-Z.rpm

(Where XXYY is the version of the ProAgent (JRE) and Z is the release number)

And this command will do the following:

• If the service is running, it will stop it.

• Copying all files needed to /opt/JAgent
• Reinstall the ProAgent (JRE) service
• If in the previous installation the ProAgent (JRE) was running, it will start the service (by default,
the service is not started during the installation).

Notes:

• The configuration files will be copied from the previous installation.

6 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 5. Uninstallation

5. Uninstallation
To uninstall the ProAgent (JRE) you have to execute the following command:

_sudo rpm -e JAgent

And this command will do the following:

• If the service is running, it will stop it.

• Uninstall the ProAgent (JRE) service.

After uninstallation, all the files inside /opt/JAgent/data will be preserved. Also, the
configuration files modified automatically during installation or modified by the
 user (these configuration files will remain backed up with the extension “rpmsave”).

All custom files added by the user remain in their location as well.

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 7

6.1. Start ProAgent (JRE) service

6. Operation
ProAgent (JRE) is installed as a service, and you have available following commands.


Because JAgent is installed as service, when the machine will restart, the service
ProAgent (JRE) will start automatically.

6.1. Start ProAgent (JRE) service

The command to start the ProAgent (JRE) service:

sudo service JAgent start

6.2. Stop ProAgent (JRE) service

The command to stop the ProAgent (JRE) service:

sudo service JAgent stop

6.3. Check the status of ProAgent (JRE) service

The command to check the status of the ProAgent (JRE) service:

sudo service JAgent status

It will return information whether the service is running or not.

8 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.1. Property File Syntax

7. Configuration
All parameters are stored in property files in the ProAgent (JRE)’s subfolder “conf” and can be viewed
or changed with a text editor. The configuration parameters of the ProAgent (JRE) can be divided into
the following groups:

• General parameters
◦ Parameters affecting the general behavior of the ProAgent (JRE).
• Communication
◦ Parameters for the communication between the ProAgent (JRE) and server.
• Event and command providers
◦ Names of the command and event providers and their parameters.
• Trace & error logging
◦ Parameters defining the ProAgent (JRE)’s trace and error logging mode.

All general parameters are stored in the file "pvagent.properties" in the “conf” folder.

The provider-specific parameters are stored in several property files, one for every provider. The files
are named "<Provider name>.properties" and are located in the “conf” folder.

The event filter configuration is stored in several property files, one for every event provider. The files
are named "<Event provider class name>Event.filter" and are located in the “conf” folder.

If not mentioned otherwise, parameters are retrieved once during startup by the ProAgent (JRE). This
means the ProAgent (JRE) has to be restarted to activate configuration changes.

7.1. Property File Syntax

Every property file is a simple list of key-value pairs in the syntax <key>=<value>, for example
Sender=JAGENT_TR. Each pair key-value has to be in only one line, the value has to be in the same
line of the key (without spaces) and it’s not possible to separate the value (neither the key) in
different lines.

Every line contains only one parameter.

Lines starting with a ’#’ as the first character are considered to be comments.

Please note that you have to specify folder separators as slashes (’/’), not as backslashes (’\’).

7.2. General parameters

Parameters relating to the logical communication between the ProAgent (JRE) and the Vynamic™
View Server specified in the file pvagent.properties.

Parameter Name
Range Default Meaning

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 9

7.2. General parameters

Parameter Name
EventStore
Text <ProAgent (JRE) The complete path to the folder where the event files are stored
folder>/data/eventst until the events have been sent to the Vynamic™ View Server.
ore
LocalServiceNames
Text <Sender>RC; List of services that the ProAgent (JRE) provides, separated by ’;’
<Sender>FT;
<Sender>EVT
RemoteServiceNames
Text AGMGR01EVT List of services that the ProAgent (JRE) connects itself to,
separated by ’;’. (value of the parameter “RemoteServiceNames”
depends on the configuration of your Vynamic™ View Server)
Sender
Text - Logical name of the ProAgent (JRE), during the installation, is
fixed like the machine name.
TemporaryDirectory
Text <ProAgent (JRE) The complete path to the folder where files for uploading and
folder>/data downloading are stored.
UseSystemClassLoader
Text 1 If ’1’, the normal system class loader is used.

The ProAgent (JRE) identifies itself via the sender name (also known as terminal ID or device name).
This name has to be unique in the whole monitored network. The sender name is case-sensitive like
ATM01 differs from Atm01.
By default the terminalID is set to the name of the machine during the installation procedure, if you
need to change the name please refer to 7.8. In the next table, you can see the list of characters not
allowed for the Terminal ID.

Characters not allowed /\%*?|"'`锟絕¶ï¿½^~[];{}

Spaces (“ “) and blank characters are also forbidden for the
Terminal ID

Table 3. Character not allowed for Terminal ID

10 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.3. Service related parameters

7.3. Service related parameters

Parameters required for the local services of the ProAgent (JRE) are specified in the file
pvagent.properties, and they are named <Sender><Service>_<Name> (Where the possible
values of Service are RC, FT and ENV, for `“Remote Command”, “File Transfer” and “Event”
respectively).
Since the first two parts of the parameter name depend on the sender and the service name, only the
last part is listed in the following tables in this subsection.

7.3.1. Local services

The ProAgent (JRE) offers the Vynamic™ View Agent Manager local services. These services can be
set up with following parameters.

Parameter Name
Range Default Meaning
Archive
Text - List of JAR files that contain the providers for this service,
separated by ’;’ Only needed if the JAR files are not located in the
system class path. If they are, please use the parameter ’Provider’
instead.
CommandThreads
1 -100 1 A number of threads for responses from the server if the ProAgent
(JRE) has issued a command.
Line
Text AGMGR01 Logical name of the communication line to the Vynamic™ View
Server.
Provider
Text - List of provider classes for this service, separated by ’;’ The
provider classes must be located in the system class path. If not,
please use the parameter ’Archive’ instead. (Either
<Sender><Service>_Archive or <Sender><Service>_Provider should
be set, not both.)
Receiver
Text AGMGR01 The logical name of the Vynamic™ View Server component that
receives the answer messages for the service.
SecurityLevel
0-2 0 Function is inactive in current version.
SessionValidityTime
0 - 3600 0 A number of seconds (the parameter
<Sender><Service>_SessionValidityTime is only read if
<Sender><Server>_SecurityLevel is not set to 0) before a logical
session is closed and re-opened again, using a new
authentication. 0 = session is never closed

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 11

7.4. Communication lines

7.3.2. Remote services

The ProAgent (JRE) is connecting as a client to the event service of the Vynamic™ View Server.

Parameter Name
Range Default Meaning
Line
Text AGMGR01 Logical name of the communication line to the Vynamic™ View
Server.
Receiver
Text AGMGR01 The logical name of the Vynamic™ View Server component that
receives the answer messages for the service.
SecurityLevel
0-2 0 Function is inactive in current version.
ServiceName
Text AGMGR01EVT Service who answers.

7.4. Communication lines

The parameters for the communication between the ProAgent (JRE) and Vynamic™ View are
specified in the file "pvagent.properties".

The ProAgent (JRE) uses the TCP/IP transport protocol to communicate with the Vynamic™ View
Server.

The TCP/IP module requires the IP address and port number of the Vynamic™ View Server and the
port number for the listen port on the own machine.

The ProAgent (JRE) can communicate with more than one server, but not at the same time.

Commands are accepted from all servers. Events are always sent to the primary server first. If the
connection to the primary server fails, the events will be sent to another server.

Parameter Name
Range Default Meaning
CommunicationLines
Text AGMGR01 A list of logical names of the Vynamic™ View Server components
that communicate with the ProAgent (JRE), separated by ’;’.
Currently, only one component is supported.
MultiServer
0-1 0 Set up the single server or multiple server communication mode,
more in Multiple server communication

Parameters required for each communication line are named "<Line>_<Name>". Since the first part of
the parameter name depends on the communication line, only the last part is listed in the table.

12 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.4. Communication lines

Parameter Name
Range Default Meaning
Class
Text com.wincornixdorf.provie The name of the class that handles the
w.socket.PvSocket communication between the ProAgent (JRE) and the
Vynamic™ View Server.
LocalPort
0 - 65535 18988 The number of the port on which the ProAgent (JRE)
listens for incoming calls from Vynamic™ View server
(the field “LocalPort” is used only if
“SupportServerEstablishConnection” is “true”, in other
case this field is ignored).
OutgoingHost
Text - Hostname or IP address of the ProAgent (JRE)’s
system. Only needed if the system has multiple
hostnames or IP addresses.
OutgoingPort
1 - 65535 18983 Number of the port the ProAgent (JRE) uses when
calling the Agent Manager.
Properties
Text RemoteHost; RemotePort; List of parameters this communication line needs,
LocalPort; separated by ’;’ Only the parameters in this list are
SupportServerEstablishCo read from the property file.
nnection
RemoteHost
Text - The hostname or IP address of the Vynamic™ View
server.
RemotePort
0 - 65535 18988 The number of the port on which the server listens for
incoming calls.
SupportServerEstablishConnection
true, false true if this value is “true”, it will open the port indicated by
“localPort” when the ProAgent (JRE) starts and it
initializes this communication line. If it’s false, it will
not open that port.

7.4.1. Multiple server communication

The ProAgent (JRE) can be configured for communication with multiple servers. Firstly, the ProAgent
(JRE) attempts to connect to the first defined server; if this connection is lost, it switches the line to
the second server. The communication is always established with exactly one server from the pool.
Up to 4 servers total are supported in the pool.

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 13

7.4. Communication lines
7.4.1.1. Enabling the multiple server communication

To enable the multiple server communication, the following settings need to be changed in the
pvagent.properties file:

• Define up to 4 communication lines with their parameters

• Set the option MultiServer=1
• Change all the <service>_Line and <service>_Receiver parametres to “MultiServer” value

7.4.1.2. Example configuration for multiple servers

14 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.4. Communication lines

Sender=c7cbox
LocalServiceNames=c7cboxRC;c7cboxFT;c7cboxEVT
c7cboxRC_Archive=
c7cboxRC_Provider=com.wincornixdorf.proview.agent.provider.checkconnection.CheckConnectionP
rovider c7cboxRC_CommandThreads=1
c7cboxRC_Line=MultiServer
c7cboxRC_Receiver=MultiServer
c7cboxRC_SecurityLevel=0
c7cboxRC_SessionValidityTime=0

c7cboxFT_Provider=com.wincornixdorf.proview.agent.provider.filetransfer.FileTransferProvider
c7cboxFT_Archive= c7cboxFT_CommandThreads=1
c7cboxFT_Line=MultiServer
c7cboxFT_Receiver=MultiServer
c7cboxFT_SecurityLevel=0
c7cboxFT_SessionValidityTime=0

c7cboxEVT_Provider=com.wincornixdorf.proview.agent.provider.heartbeat.PvHeartBeatProvider
c7cboxEVT_Archive=
c7cboxEVT_CommandThreads=1
c7cboxEVT_Line=MultiServer
c7cboxEVT_Receiver=MultiServer
c7cboxEVT_SecurityLevel=1
c7cboxEVT_SessionValidityTime=0

RemoteServiceNames=AGMGR01EVT
AGMGR01EVT_Line=MultiServer
AGMGR01EVT_Receiver=MultiServer
AGMGR01EVT_SecurityLevel=0

# definition of communication lines

CommunicationLines=AGMGR01;AGMGR02
MultiServer=1

# AGMGR01
AGMGR01_Class=com.wincornixdorf.proview.socket.PvSocket
AGMGR01_Properties=RemoteHost;RemotePort;LocalPort;SupportServerEstablishConnection
# ;OutgoingPort;OutgoingHost
AGMGR01_RemoteHost=192.168.2.1
AGMGR01_RemotePort=18988
AGMGR01_LocalPort=18981
AGMGR01_SupportServerEstablishConnection=true
AGMGR01_OutgoingPort=18983
#AGMGR01_OutgoingHost=$OUTGOINGHOST$

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 15

7.5. Secure TCP/IP connections using TLS

# AGMGR02
AGMGR02_Class=com.wincornixdorf.proview.socket.PvSocket
AGMGR02_Properties=RemoteHost;RemotePort;LocalPort;SupportServerEstablishConnection
# ;OutgoingPort;OutgoingHost
AGMGR02_RemoteHost=192.168.2.3
AGMGR02_RemotePort=18988
AGMGR02_LocalPort=18982
AGMGR02_SupportServerEstablishConnection=true
AGMGR02_OutgoingPort=18983
#AGMGR02_OutgoingHost=$OUTGOINGHOST$

UseSystemClassLoader=1
TemporaryDirectory=/opt/JAgent/data
EventStore=/opt/JAgent/data/eventstore

LibraryPath=/opt/JAgent/lib/jagent/
SsopJarName=ssop-1.2.60.jar

7.5. Secure TCP/IP connections using TLS

The Java Agent can be configured to connect to a gateway or the Vynamic™ View Server via secure
TLS. TLS is enabled when a Java certificate keystore and its access credentials are provided in the
configuration file.

To securely connect, the server certificate must be trusted by the Java Agent. It means the keystore
must contain a root certificate of the server certificate.

The server may require the Java Agent to authenticate. In this case, the Java Agent keystore must
contain a client certificate that is trusted by the server.

The TLS communication provided with the Java Agent is compatible only with TLS (unidirectional)
modules of the Vynamic™ View Server. For this reason the Java Agent must be configured to connect
to the port 38988. TLS is configured in "pvagent.properties"

Parameter Name
Range Default Meaning
Keystore
Text Path to the Java keystore file. The Java Gateway must have a read
acces to the file.
KeystorePassword
Text The password to open the keystore, which was generated when
the keystore was created.
ClientCertificatePassword
Text The client private key password. It can be avoided when no client
authentication is required.
SslThumbprint

16 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.6. Must match server certificate. Optional - does not have to be used

Parameter Name
Text Thumbprint of server certificate. When this property is defined, the
server certificate must match with the thumbprint defined in this
property.
SslSubject
Text Subject field of server certificate. When this property is defined,
the server certificate must match with the subject defined in this
property. A subject field of a certificate typically consists of a
Common Name (CN),a Distinguished Name (DN) and other
variables, written in a form: CN=name, DN=name, …. For this
property, use only the value of Common Name (the name after
CN=).

SslIssuer
Text Issuer field of server certificate. The form is the same as for the
certificate subject mentioned above.

Example configuration to enable TLS in pvagent.properties is:

AGMGR01_RemoteHost=192.168.56.102
AGMGR01_RemotePort=38988

Keystore=/opt/keystore.jks
KeystorePassword=Password
ClientCertificatePassword=Keypasswd # optional

7.6. Must match server certificate. Optional - does not

have to be used

SslThumbprint=b0 77 1f 85 a1 c5 8d 87 e1 72 e9 ec 13 86 ae 8a 8a f9 89
ca
SslSubject=subject
SslIssuer=issuer

7.7. Tracing
ProAgent (JRE) traces information, warnings, and errors into an ASCII text file. If the size of this file
exceeds the configured limit, it is backed up and a new trace file is created.

Apache™ "log4j" is used for tracing purposes.

The trace file is named "PVAGENT.TRC" and is located in the folder <ProAgent (JRE)
folder>/data/trace".

Parameters for tracing are specified in file "log4j.properties" in folder "<ProAgent (JRE) folder>/conf".
All parameters are named "log4j.[appender.<AppenderName>.]<parameter>".

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 17

7.7. Tracing

Parameter Name
Range Default Meaning
rootLogger
Text INFO, T, M, E Global trace level, followed by a list of <AppenderName>
definitions, all separated by ’, ’
log4j.appender.<AppenderName>
Text org.apache.log4j.Roll The complete name of the appender type
ingFileAppender
log4j.appender.<AppenderName>.File
Text <ProAgent (JRE) The complete name of the trace file.
folder>/data/trace/<
name>
log4j.appender.<AppenderName>.MaxFileSize
Text 10000KB The size of a trace file before it is backed up and a new trace file is
written.
log4j.appender.<AppenderName>.MaxBackupIndex
0 - 20 10 A number of backup generations.
log4j.appender.<AppenderName>.ConversionPattern
Text %d %-5p [%-20t] %- Pattern for formatting a trace entry. Please refer to the log4j
80m [%l]%n documentation for a description of the syntax.

Detailed information about "log4j" settings, trace levels, etc. can be found on
http://logging.apache.org/log4j/1.2/manual.html

18 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.8. Example log4J.properties file

7.8. Example log4J.properties file

log4j.rootLogger=INFO, T, M, E
log4j.appender.T=org.apache.log4j.RollingFileAppender
log4j.appender.T.File=/opt/JAgent/data/trace/PVAGENT.TRC
log4j.appender.T.MaxFileSize=10000KB
log4j.appender.T.MaxBackupIndex=10
log4j.appender.T.layout=org.apache.log4j.PatternLayout
log4j.appender.T.layout.ConversionPattern=%d %-5p [%-20t] %-80m [%l]%n
log4j.appender.M=org.apache.log4j.RollingFileAppender
log4j.appender.M.File=/opt/JAgent/data/trace/PVAGENT.SSTP.TRC
log4j.appender.M.MaxFileSize=20000KB
log4j.appender.M.MaxBackupIndex=1
log4j.appender.M.layout=org.apache.log4j.PatternLayout
log4j.appender.M.layout.ConversionPattern=%d %-5p [%-20t] %m%n
log4j.appender.M.Threshold=INFO
log4j.appender.E=org.apache.log4j.RollingFileAppender
log4j.appender.E.File=/opt/JAgent/data/trace/PVAGENT.ERR
log4j.appender.E.MaxFileSize=20000KB
log4j.appender.E.MaxBackupIndex=1
log4j.appender.E.layout=org.apache.log4j.PatternLayout
log4j.appender.E.layout.ConversionPattern=%d %-5p [%-20t] [%l] %m%n
log4j.appender.E.Threshold=ERROR

7.9. Change the name of the terminalID

During the installation, the RPM procedure sets the name of the machine as terminalID. If you want to
change the terminalID to use another different, you have to follow the next steps (all in the file
pvagent.properties):

1. Set the correct TerminalID in the Sender.

2. Set the LocalServiceNames as <TerminalID>RC, <TerminalID>FT (and optional <TerminalID>EVT).
Then you have to modify the LocalServiceNames value and all the keys related to
<TerminalID>RC, <TerminalID>FT.

An Example of pvagent.properties using “terminalid” as TerminalID follows:

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 19

7.9. Change the name of the terminalID

Sender=terminalid
LocalServiceNames=terminalidRC;terminalidFT;terminalidEVT

terminalidRC_Provider=com.wincornixdorf.proview.agent.provider.checkconnection.CheckConnecti
onProvider;com.wincornixdorf.proview.agent.provider.system.PvSystemProvider
terminalidRC_Archive=
terminalidRC_CommandThreads=1
terminalidRC_Line=AGMGR01
terminalidRC_Receiver=AGMGR01
terminalidRC_SecurityLevel=0
terminalidRC_SessionValidityTime=0

terminalidFT_Provider=com.wincornixdorf.proview.agent.provider.filetransfer.FileTransferProvider
terminalidFT_Archive=
terminalidFT_CommandThreads=1
terminalidFT_Line=AGMGR01
terminalidFT_Receiver=AGMGR01
terminalidFT_SecurityLevel=0
terminalidFT_SessionValidityTime=0

terminalidEVT_Provider=com.wincornixdorf.proview.agent.provider.heartbeat.PvHeartBeatProvider;
com.wincornixdorf.proview.agent.provider.textfile.PvTextFileProvider
terminalidEVT_Archive=
terminalidEVT_CommandThreads=1
terminalidEVT_Line=AGMGR01
terminalidEVT_Receiver=AGMGR01
terminalidEVT_SecurityLevel=0
terminalidEVT_SessionValidityTime=0

RemoteServiceNames=AGMGR01EVT

AGMGR01EVT_Receiver=AGMGR01
AGMGR01EVT_SecurityLevel=0
AGMGR01EVT_ServiceName=AGMGR01EVT

CommunicationLines=AGMGR01

AGMGR01_Class=com.wincornixdorf.proview.socket.PvSocket
AGMGR01_Properties=RemoteHost;RemotePort;LocalPort;SupportServerEstablishConnection
AGMGR01_RemoteHost=192.168.2.155
AGMGR01_RemotePort=18988
AGMGR01_LocalPort=18981
AGMGR01_SupportServerEstablishConnection=true
AGMGR01_OutgoingPort=18983

UseSystemClassLoader=1
TemporaryDirectory=/opt/JAgent/data
EventStore=/opt/JAgent/data/eventstore

LibraryPath=/opt/JAgent/lib/jagent/
SsopJarName=ssop-<version>.jar

20 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 7.10. Service wrapper

7.10. Service wrapper

The Java Gateway is automatically registered as a system service via a service wrapper.
Configuration of the wrapper is located in the file wrapper.conf. This file is already pre-configured
to correctly start the service and does not have to be changed. In certain cases such as debug or
troubleshooting, this file can be modified to tweak service startup.

Parameter Name
Range Default Meaning
wrapper.java.additional.<n>
Text Additional parameter to start JVM with. The value <n> is a number
and this configuration can be repeated with different number for
each configuration. Example

• wrapper.java.additional.1=A
• wrapper.java.additional.2=B
• wrapper.java.additional.3=C

wrapper.on_exit.<n>
Text SHUTDOWN Action for the service wrapper to take after the task ends with the
code <n>. Another option to set is RESTART. For instance, the
service will be restart for exit code 1 wrapper.on_exit.1=RESTART
wrapper.on_exit.default
Text SHUTDOWN The default action for the service wrapper to take after the task
unexpectedly ends. Another option to set is RESTART.
wrapper.max_failed_invocations
Number 10 The number of failing starts before the service restart is given up.
This settings have effect if the RESTART action described above is
used.
wrapper.startup.timeout
Number 30 Time limit in seconds. The task is considered as failed if it does
not start in this time frame.
wrapper.successful_invocation_time
Number 300 Time limit in seconds. The failed invocation counter is reset if the
task runs longer than the time defined in this property.

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 21

8.1. Overview

8. Event and Command Providers

8.1. Overview
The ProAgent (JRE) is delivered with several event and command providers. This chapter describes
their purpose, configuration, and usage.

8.1.1. Standard Event Providers

Event providers are the event sources of the ProAgent (JRE). An event provider captures all events
from one source, converts them into a standard format (also termed “original event message”) and
reports them to the ProAgent (JRE) kernel. An event provider typically performs no filtering on events
that have occurred. This is the task of the filter module.
Bellow, you find a list of the standard event providers and their purpose

Purpose Provider
Send heartbeat events Heartbeat provider
Monitor text files Text files provider
Send FDM events FDM events provider

Table 4. Standard Event Providers

8.1.2. Standard Command Providers

Command providers are responsible for executing device requests, remote operations, and file
transfer. One command provider can support one or more functions, and one function can be
supported by one or more providers.
Below you find a list of all standard commands providers and their purpose.

Purpose Provider
Remote operations Set the system date and time System provider
Get the contents of a folder
File transfer Transfer files from or to the Vynamic™ View File Transfer provider
Server
Miscellaneous Process any command the user likes by Transparent command
starting a program on the machine provider

Table 5. Standard Command Providers

8.1.3. General configuration rules

All configuration parameters for event and command providers can be found in property files, each
assigned to the appropriate provider. Parameters in these files follow the standard Java parameter
syntax: <parameter name>=<parameter value>

22 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 8.2. File Transfer Provider

8.2. File Transfer Provider

Type Commands
Purpose Transfer files from or to the Vynamic™ View Server and get folder lists
Supported commands • 320 (SSOP_UPLOAD_FILE)
• 321 (SSOP_DOWNLOAD_FILE)
• 322 (SSOP_CANCEL_FT)
• 324 (SSOP_SEND_FTDATA)
• 325 (SSOP_RECEIVE_FTDATA)

JAR name agent-filetransferprovider-XXYY.jar

Configuration file -

8.2.1. Description
This provider is responsible for file transfer commands. It is used to transfer files from the device to
the Vynamic™ View Server or vice-versa. The names of those files are specified on the Vynamic™
View side.

Upload file type in Console

 Only “Normal File” type is supported in current version of ProAgent (JRE). If user
chooses different file type in the Upload file dialog, the upload will fail.

8.2.2. Configuration
The file transfer provider does not need any configuration.

8.3. Heartbeat Provider

Type Events
Purpose Send heartbeat events
Supported commands -
JAR name agent-heartbeatprovider-XXYY.jar
Configuration file PvHeartBeatProvider.properties

8.3.1. Description
This provider sends keep-alive events in configurable intervals. This is useful in environments where
the Vynamic™ View Server is not allowed to poll the ProAgent (JRE)s (for example because it is
located behind a firewall)

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 23

8.4. Send Check Command Provider

8.3.2. Configuration
The heartbeat provider is configured in the property file PvHeartBeatProvider.properties.

Parameter Name
Range Default Meaning
NotSendEventIntervals
List of times - Time(s) of day when no events are sent (used only when
“SendEventMode” is set to “1”). For example: 03:00-04:00
07:00-08:00
SendEventIntervalSec
1-9999999 60 Interval in seconds between two events (Used only when
“SendEventMode” is set to “1”).
SendEventMode
0,1 1 Determines how the timer interval is being calculated:

• “0”: Events are sent at the times configured in

“SendEventTimes”
• “1”: Events are sent frequently with an interval specified
in “SendEventIntervalSec”. You can configure times
when the events are not sent in
“NotSendEventIntervals”

SendEventTimes
List of times - Time(s) of day when an event is sent (this parameter is only
read if “SendEventMode” is set to “0”)
For example: 00:00 06:00 12:00 18:00

8.3.3. Events
The heartbeat provider reports the following events:

Meaning Format
The time when a keep-alive event has arrived “alive <10-digit number>”

8.4. Send Check Command Provider

Type Command
Purpose Send check connection
Supported commands -
JAR name agent-sendcheckconnectionproviderr-XXYY.jar
Class name com.wincornixdorf.proview.agent.provider.checkconnection.Chec
kConnectionProvider

24 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 8.5. System Provider

Configuration file PvSendCheckConnectionProvider.properties

8.4.1. Description
This provider periodically sends the Check Connection command to the server. This is useful to keep
connection active.

8.4.2. Configuration
This provider is configured in the property file PvSendCheckConnectionProvider.properties

Parameter Name
Range Default Meaning
SendCommandIntervalSec
Number 60 Time delay in seconds between each commands.

8.5. System Provider

Type Commands
Purpose Execute system commands
Supported commands • 159 (SSOP_SET_DATETIME)
• 160 (SSOP_GET_DATETIME)
• 163 (SSOP_GET_DIRECTORY)
• 173 (SSOP_START_PROGRAM)

JAR name agent-systemprovider-XXYY.jar

Configuration file PvSystemProvider.properties

8.5.1. Description
This provider calls system functions to execute SSOP commands. It is used to:

• Get the context of a folder (SSOP_GET_DIRECTORY)

• Get the date/time (SSOP_GET_DATETIME)
• Set the date/time (SSOP_SET_DATETIME)
• Start a program (SSOP_START_PROGRAM)

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 25

8.6. Text File Provider

Permissions for commands

For the following commands you need root permissions, then it will return always
error if the user used to start the ProAgent (JRE) has not root permissions:

 • SSOP_SET_DATETIME

Also, the auto time synchronization must be turned off. Otherwise, the time will
resynchronize with the internet.

Start Program Timeout

When a started program has for instance 10 second execution time and the timeout
is set for, say, 9 seconds, it might happen that the execution will not time out and
the started program exit naturally. This is due to the fact that there might be a short
 delay (1 or 2 seconds) between sending the program killing signal and its actual
death.

This function is therefore not suitable for time-critical tasks (i.e. tasks that must be
killed exactly after X seconds).

8.5.2. Configuration
The system provider is configured in the property file PvSystemProvider.properties

Parameter Name
Range Default Meaning
FileProgramRestartInfo
String Conf/PvSystemProvi Properties file to store information about the programs are not
derRestartInfo.prope started yet
rties

8.5.3. Events
The system provider could report the following events:

Meaning Format
The program is going to start “Program ‘<name of the program>’ will be started now”
The program has finished “Program ‘<name of the program>’ ended. Exit code = <retValue>.
Output = ‘<output of the program>’”

8.6. Text File Provider

Type Events
Purpose Monitors a text file
Supported commands -
JAR name agent-textfileprovider-XXYY.jar

26 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 8.6. Text File Provider

Configuration file PvtextFileProvider.properties

8.6.1. Description
This provider monitors one ASCII text file. Each new line in this file generates an event for the
ProAgent (JRE).

The current read position is stored in the file PvTextFileProvider.restart. If this file does not
contain any entry for the monitored file, the read pointer is positioned to the end of the file and the
monitoring starts with the next entered line.

When the file size decreases during monitoring the provider assumes that the file has been recreated
and positions to the first line of the file.

8.6.2. Configuration
The heartbeat provider is configured in the property file PvtextFileProvider.properties

Parameter Name
Range Default Meaning
FileName
Text - Complete path and name of the file to monitor
PollingInterval
1-999 10 Seconds between two file checks

Example:

FileName=/opt/atm_app/logs/journal
PollingInterval=20

Restrictions
Please note the following restrictions when using the event provider for text files:

• The text file must be in UNIX or DOS (Windows) format.

• The text file must not be terminated with EOF
 • The event provider polls the monitored file periodically. Loss of data is possible
when the text file is deleted during monitoring. When a monitored file is deleted,
it has to be ensured that the deletion is done after the event provider has
processed the final line of the file.
• One line has a maximum length of 4096 characters. The ProAgent (JRE)
processes only the first 254 characters of each line.

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 27

8.7. FDM Event Provider

8.6.3. Events
The text file provider reports the following events:

Meaning Format
A new line has been written into the monitored text file <Line contents>

8.7. FDM Event Provider

Type Events
Purpose Send FDM events
Supported commands -
JAR name gateway-XXYY.jar
Configuration file PvGatewayFdmEventProviderEvent.filter

8.7.1. Description
This provider is responsible for sending FDM related events. It is mandatory part of the FDM provider.

8.7.2. Configuration
The FDM event provider is configured in the filter file
PvGatewayFdmEventProviderEvent.filter. For detailed information about the filter files,
please refer to the chapter Event filter module

8.7.3. Events
To find out more details about the list of available FDM related event, refer to the chapter Internal
Events in Vynamic™ View Operation Manual.

28 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 9.1. Overview

9. Event Processing
9.1. Overview
Since events can originate from many different sources, the structure of the available data can vary
greatly. In order to enable uniform processing of such events, all event providers must create a
character string. The SSOP messages that are sent to the Vynamic™ View Server require that a
unique event number is assigned to each event. A large number of possible events makes it advisable
to adapt a flexible approach to this unique number assignment, rather than programming it in the
ProAgent (JRE) itself.

The possibility of selecting the events which are to be reported and suppressing those that are not of
any interest is provided by the ProAgent (JRE).

9.2. Event Filter Module

The filter module receives event messages from all event providers. Using this data, the module
attempts to identify the event and to assign a unique event number. These are the original event
numbers which are transferred to the Vynamic™ View Server.

The filter can be configured according to individual requirements by editing the filter configuration file
for each event provider.

9.2.1. Configuration
Each filter configuration file contains either a list of regular expressions which identify the valid
events, or a list of valid event numbers.
The name of the filter file is made up of the Javabean class name of the provider (see for example
section ”Heartbeat Provider”) and the filter class name "Event.filter", for example,
PvHeartBeatProviderEvent.filter.

9.2.2. Identifying events by their contents

If a provider does not generate event numbers, the numbers are assigned by the filter module. This is
done by searching specified patterns (regular expressions, refer to in the chapter “Syntax of Regular
Expressions”) in the event text.
The syntax for an entry is <number>=<regular expression>. The first matching pattern
determines the event number.

9.2.3. Identifying events by their number

If a provider generates event numbers by itself, the valid numbers are listed in the syntax <number
1>,<number 2>, …, <number n>. If this syntax is used, the keyword :MESSAGENUMBER must be
in the filter file on separate line and written before the event numbers itself.

9.2.4. Syntax of regular expressions

The meta characters of the regular expression language are:

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 29

9.2. Event Filter Module

|^$.*+?()[]\{\}\

Language operators Meaning

Ab Fixed character string
. Represents any single character of the string
^ Represents the beginning of a string. This special meaning is only valid at
the beginning of the expression, or after a “(“ or a “|”
$ Represents the end of a string. This special meaning is only valid at the
end of the expression or before a “)” or a “|”.
[abc], [^abc], [a-z] This represents any character out of the list of characters given in square
brackets. A hyphen ‘-’ between two characters specifies a range of
characters in ASCII ordering. If the first character in the list is a caret ‘^’,the
pattern matches any character except the ones given in the list. If a ‘]’ or ‘-’
is the first character in the list, the meta characters will be taken literally.
For ‘-’ this is also true if it occurs at the end of a list. Nonprintable
characters may be given as escaped ASCII values of three digits length
([\007\008]). All metacharacters except the ‘\’ lose their special meaning if
they occur in a character list ([.*] matches only a dot or an asterisk
\ The backslash cancels the meaning of any metacharacter, the following
character is taken literally ( \* matches any *, \\ matches any \)
\1-\9 Represents the n‘th subexpression enclosed in parentheses ‘()’ that is
found earlier in the given expression. Parenthesized expressions are
counted from the left. It is an error if no ‘n’th subexpression exists.
Example: ("((a)|b)\2" matches "aa" or "ba")
regex* Represents zero or more strings that would match the expression ‘regex’.
Example: "a*" matches "", "a", "aa" and so on
regex+ Represents one or more strings that would match the expression ‘regex’.
Example: "a+" matches "a", "aa" and so on
regex? Represents zero or one string that would match the expression ‘regex’.
Example: "a?" matches "" and "a"
regex{n} Represents n strings that would match the expression ‘regex’.
Example: "a{3}" matches "aaa"
regex\{n,\} Represents n or more strings that would match the expression ‘regex’.
Example: "a\{3,\}" matches "aaa", "aaaa", "aaaaa", and so on
regex\{n,m\} Represents n to m strings that would match the expression ‘regex’.
Example: "a\{3,4\}" matches "aaa" and "aaaa"
regex1|regex2 Represents either expression 1 or 2. (regex) Parentheses allow the
grouping of expressions.
Example: ((a|b)c|(d|e)f)g matches "acg", "bcg", "dfg" or "efg".

Operator precedence Character

Escaped characters \special character
Bracket expression []
Grouping ()
Single-character-duplication * + ? \{m,n\}"

30 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 9.3. Event Subscribers

Operator precedence Character

Concatenation
Anchoring ^$
Alternation |

Regular expression implementation

Unlike in other implementations of regular expressions you have to enclose your
 regular expression with the wildcards .* (equals ‘all characters’) if the regular
expression can occur anywhere in the event text. For example, you have to enter
.*MatchMe.* instead of MatchMe.

9.2.5. Example of a filter configuration file

71000=.*Card inserted.*
71001=.*Card retained.*
71002=.*Card ejected.*
72000=.*

80001=EP:\.1\.3\.6\.1\.4\.1\.14760;.*VBL:\.1\.3\.6\.1\.4\.1\.14760\.2\.1\.2\.1
1=01:123
80002=EP:\.1\.3\.6\.1\.4\.1\.14760;.*VBL:\.1\.3\.6\.1\.4\.1\.14760\.2\.1\.2\.1
1=01:000

9.3. Event Subscribers

9.3.1. Overview
During the handling of an event, it can be processed by custom-made modules. These modules are
called event subscribers because they subscribe to receiving events of one or more types. Event
subscriber can be called in the following situations:

• After an event has been passed the event filter

• After an event has been sent to the Server

9.3.2. Subscriber Module

The subscriber module receives event messages from all event providers (according to the
configuration, before or after sending the event). And this module will send the event to the different
subscribers, using as order the priority number of each subscriber.

To add a subscriber, register the subscriber module in the configuration of the local EVENT service,
refer to the example. If there are more subscribers to be registered, they are separated by a semicolon
(‘;’) and the whole registration of subscribers must be completely on single line.

Example, we added the subscribers “Event Log Subscriber”, “Active MQ Subscriber” and ”Command
Execution Subscriber” to the following configuration for the RC service (in pvagent.properties):

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 31

9.3. Event Subscribers

MyServiceEVT_Provider=com.wincornixdorf.proview.agent.provider.heartbeat.PvHeartBeatProvider;
com.wincornixdorf.proview.agent.provider.textfile.PvTextFileProvider
MyServiceEVT_Subscriber=com.wincornixdorf.proview.agent.eventsubscriber.EventLogSubscriber;
com.wincornixdof.proview.agent.eventsubscriber.ActiveMQSubscriber;com.wincornixdorf.proview.
agent.eventsubscriber.CmdExecSubscriber (All the event subscribers must be written on single line).
MyServiceEVT_Archive=
MyServiceEVT_CommandThreads=1
MyServiceEVT_Line=AGMGR01
MyServiceEVT_Receiver=AGMGR01
MyServiceEVT_SecurityLevel=1
MyServiceEVT_SessionValidityTime=0

All the subscribers have besides their specific properties following common configuration.

Parameter Name
Range Default Meaning
Prio
Number - Priority of the event subscriber (highest value, highest priority)
CallBeforeSendEvent
N, Y N To receive the event in the subscriber before (Y) or after (N)
sending the event to the Server

9.3.3. Event Log Subscriber

Type Subscriber
Purpose Send the events to log file
JAR name agent-textfileprovider-XXYY.jar
Subscriber class com.wincornixdorf.proview.agent.eventsubscriber.EventLogSubsc
riber
Configuration file EventLogSubscriber.properties

9.3.3.1. Description

This subscriber writes the events to a log file

9.3.3.2. Specific configuration

Parameter Name
Range Default Meaning
LogFileName
String - The name of the file where the logs are going to be written
LogFileSize
Number 1024 The maximum size of the file (there will be only one log file for
events)
WaitBeforeDeletion

32 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 9.3. Event Subscribers

Parameter Name
Number 3 When the log file is greater than the value of LogFileSize, the file
will be renamed as “.bak”, and the subscriber will wait the
milliseconds of “WaitBeforeDeletion” before deleting the “bak” file.

9.3.4. ActiveMQ subscriber

Type Subscriber
Purpose Send the events to ActiveMQ
JAR name agent-activemqsubscriber-XXYY.jar
Subscriber class com.wincornixdorf.proview.agent.eventsubscriber.ActiveMQSubs
criber
Configuration file ActiveMQSubscriber.properties

9.3.4.1. Description

This subscriber will send the events to ActiveMQ. Please note that the module ActiveMQ Broker has
to be installed, configured, and activated on the Apache web server.

9.3.4.2. Specific configuration

Parameter Name
Range Default Meaning
BrokerURI
URL failover:tcp://localhost:61616 The transport protocol, the address, and the port
number of the Apache server. This URI can be
prefixed with a failover option, for more
information, refer to the info box below.
ClientAck
Y,N N Specifies whether the ActiveMQ Acknowledge
Mode is set to CLIENT_ACKNOWLEDGE (‘Y’) or
AUTO_ACKNOWLEDGE (‘N’).
DestURI
Text TOOL.DEFAULT The name of the event destination on the Apache
server. If the destination does not exist it will be
created automatically when the first event is
forwarded.
PersistentDeliveryMode
Y, N N Specifies the persistent delivery mode of event
on the Apache server (broker). If events are
persisted (‘Y’) to disk/database they will survive
a broker restart. In case of non-persistent
delivery (‘N’), you will lose all in-transit events
after restart of a broker.
StoreUnsentEvents

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 33

9.3. Event Subscribers

Parameter Name
Y, N N Specifies whether the events should be stored in
an EventStore in case the ActiveMQ connection
breaks up. These events are resented to the
ActiveMQ when the connection is reestablished.
UseTopic
Y, N N Specifies whether the event destination on the
Apache server should be created as a topic (‘Y’)
or as a queue (‘N’)
EventStore
Text <ProAgent (JRE) folder>/data/eventstore The complete path to the folder where the unsent
event files are stored until the ActiveMQ
connection is reestablished. These events will
then be resent.

ActiveMQ Broker URI options

ActiveMQ can be run with failover option. This feature of ActiveMQ is enabled by
prefixing the BrokerURI with “failover” keyword, e.g.
“BrokerURI=failover:tcp://localhost:61616”.

 When the failover is activated, ActiveMQ automatically periodically attempts to

reestablish a connection with the broker in case this connection is lost.

Without the failover transport option, the connection is terminated,

ActiveMQSubscriber goes into an error state, and the ProAgent (JRE)s needs to be
restarted in order to recover.

9.3.5. Command Execution Subscriber

Type Subscriber
Purpose Execute a command
JAR name agent-commandexecutionsubscriber-XXYY.jar
Subscriber class com.wincornixdorf.proview.agent.eventsubscriber.CmdExecSubscriber
Configuration file CmdExecSubscriber.properties

9.3.5.1. Description

This subscriber executes a command if an event with a specific number occurs. The result of the
executed command is written into a log file.

9.3.5.2. Specific configuration

Parameter Name
Range Default Meaning
ExecutionMode

34 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0

 9.3. Event Subscribers

Parameter Name
asynchronous, asynchronous The execution mode of the commands.
synchronous
• Asynchronous: After the commands has been started,
the Agent continues with the command and event
processing
• Synchronous: After the command has been started, the
Agent stops the command and event processing until
the execution is finished

LogFileName
Text - Name of the log file
LogFileSize
0-5120 1024 Size of the log file in KB
<Event number>
Text N Defines a program that is executed if the event with the
number <Event number> occurs

Doc. Version: 1.0 Vynamic™ View ProAgent JRE - Operation Manual 35

Publisher

Publisher
Published by
Diebold Nixdorf Global Solutions B.V.
Papendorpseweg 100
3528 BJ Utrecht
The Netherlands
DieboldNixdorf.com

All rights reserved, particularly in relation to the grant of a patent or the registration of a utility model.
Subject to availability and technical modifications.

Copyright © Diebold Nixdorf, Inc. (2019) – All rights reserved

36 Vynamic™ View ProAgent JRE - Operation Manual Doc. Version: 1.0