Frequently Asked Questions

This section contains answers to the most common questions. To help you navigate more easily, we’ve grouped them by topic:

• Legal Questions and Security
• System Implementation and Configuration
• Installation and Administration
• Technical Requirements and System Architecture
• Monitoring and Monitoring Agents
• Business Analytics and Dashboards
• Working with External Data
• Task Mining and Process Mining
• Automation and Process Analysis
• Documentation and Consulting
• Extensibility and Customization
• Technical Support

Legal Questions and Security

Is the monitoring agent noticeable to the employee?

The monitoring agent runs in the background: it displays no notifications, system tray icons, or other UI elements that could draw the user’s attention. Detecting it independently is possible but highly difficult—for instance, only through in-depth analysis of system processes or installed software. Under normal conditions, an employee will not be aware of the agent’s presence unless explicitly informed.

In standard operation, the agent does not block, slow down, or alter the behavior of installed applications. However, as with any software, rare unexpected interactions with other applications may occur—particularly if those applications contain bugs or employ non-standard system interaction methods.

What security measures are used to protect data in Operavix?

The following measures are implemented:

• Password encryption
• Hashing
• TLS encryption between components
• Role-based access control with user activity logging
• Other security measures

Security is embedded throughout Operavix’s lifecycle. We continuously analyze and enhance protective mechanisms: every build undergoes automated vulnerability scanning, and the system architecture follows secure development principles. Our team actively monitors emerging threats and updates defenses in line with industry best practices and regulatory standards.

The monitoring agent captures clipboard content. Are passwords copied from a password manager collected?

No, passwords are not recorded. Operavix automatically detects password fields and excludes them from data collection—including when their values reside in the clipboard.

For additional protection of sensitive information, data from other fields is anonymized via hashing, enabling identification of unique values without revealing their actual content.

Moreover, when keys are pressed, the monitoring agent records only the fact of keystroke activity, not the typed characters. This data is used solely to determine when the user was actively working at the computer.

Agent logs may include information about hotkey presses. However, combinations such as Shift + single-character key (e.g., for typing uppercase letters) are explicitly excluded from logging.

How to ensure confidentiality of collected screenshots and activity data?

To ensure confidentiality of collected data:

• Restrict data access using role-based permissions
• Configure data retention policies
• Use encryption and secure communication channels
• Anonymize data where appropriate

System Implementation and Configuration

What effort is required from the customer during implementation?

The main effort falls on the pre-project phase and implementation support.

Key effort areas:

• Pre-project phase:
  • Agreement on allocation of technical resources
  • Coordination with the information security department
  • Provision of remote access for system configuration
  • Installation of the server component and agents on test and target workstations
  • If data exports from information systems (e.g., for Process Mining) are planned, technical specifications must be prepared on the customer’s side to enable such exports
• Implementation phase:
  • Consultations for administrators and project curators
  • User monitoring and support
  • We provide comprehensive documentation and support the customer throughout all stages

Which integrations are available during the pilot phase?

For the pilot, we recommend starting with Active Directory integration; other integrations from the constructor are technically available but are best configured during the production rollout.

During the pilot, we recommend beginning with Active Directory integration, as it enables quick user onboarding and simplifies access rights configuration—a proven approach based on our implementation experience.

Technically, the system supports other integrations: you can connect solutions from the integration constructor, including Microsoft Exchange, Jira, and more. However, for full functionality and stable production operation, we recommend configuring these during the industrial deployment phase—taking into account your infrastructure and business process specifics.

If you require additional integrations during the pilot, discuss this with your account manager or support team. We will help assess feasibility and prepare the required configuration.

We don’t have spare server capacity for a Process Mining pilot—what should we do?

We can run the pilot in our secure environment, without requiring the customer to allocate servers.

How it works:

1. You prepare a data export from your information system (e.g., operation logs, timestamps).
2. Data is transferred to us via an agreed secure channel.
3. We process the data, build process models, and generate visualizations.
4. Results are delivered as dashboards.

This approach allows launching a pilot without allocating internal server resources.

How do I connect Operavix to Active Directory?

Connection is configured in the User Synchronization settings section.

To set up user synchronization with Active Directory:

1. Go to Settings → Administration → User Synchronization.
2. Add the domain controller and specify the login and password.
3. Configure domain objects and attributes for synchronization.

Can other authentication systems be used instead of AD?

Yes, in addition to Active Directory, SAML, Kerberos, OpenID, and local authentication are supported.

Detailed information is provided in the Adding Authentication section.

Where can I find the latest Operavix and agent distribution packages?

The monitoring agent distribution can be downloaded directly from the system’s web interface.

Installation and Administration

How do I install or update the monitoring agent on Windows/Linux?

The agent is installed and updated the same way—using the distribution package of the new version.

• For Windows, the primary format is the .msi installer package, recommended for centralized deployment via Group Policy (GPO). The .exe installer is intended for exceptional cases—e.g., pilot rollouts or manual installation on individual machines.
• For Linux, .rpm and .deb packages are available.

Detailed instructions are provided in Managing the Monitoring Agent.

How do I update the Operavix system to a new version?

Updates are performed using distribution packages provided by Operavix.

The process includes stopping services, installing the new version, and restarting. A step-by-step guide is available in Updating Operavix.

How do I activate a license key?

Key activation is performed in the Licensing section, located under the Settings tab and accessible only to users with the Administrator access role.

To activate a key, click the corresponding button in the top-right corner. In the dialog that appears, enter the key name and the provided license key, then click Activate.

What happens when a license expires?

When the license expires, the system is locked.

Further behavior depends on the user’s privileges:

• If the user does not have the License Management privilege with the Create (C) operation, an error message appears upon login: No valid activation key found.
• If the user does have the License Management privilege with Create (C), the license activation page opens upon login:
  • If a valid key is entered and Activate is clicked, the license is automatically extended to the expiration date specified in that key, and the user is redirected to the workspace list.
  • If an invalid key is entered, clicking Activate displays the error: Invalid activation key.

Can a pilot license be temporarily extended?

After the pilot project ends, you receive 30 days of complimentary system access. Use this time for independent exploration and platform evaluation.

What happens when the advanced monitoring license is deactivated?

When the advanced monitoring license is deactivated, the system automatically revokes active licenses from users.

Since it’s impossible to determine which users should retain access, the selection is randomized: some users lose their license, while others retain it.

What JVM parameters are recommended for the server?

For the Operavix application, the primary and recommended JVM parameter is the maximum heap size, set via -Xmx through the JVM_MAX_MEMORY environment variable.

General recommendations:

• Set JVM_MAX_MEMORY to 60–90% of the server’s free RAM, but no more than 80% of total physical memory
• Ensure at least 4 GB of free memory remains for stable OS operation
• Default value is 4 GB (-Xmx4G)

Parameter examples:

On Linux, via environment variable at container/service startup:

-e JVM_MAX_MEMORY='8G'

On Windows, via the registry:

1. Open the Registry Editor as Administrator.
2. Navigate to: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Operavix.
3. Edit the ImagePath value—e.g., replace -Xmx2G with -Xmx8G.
4. Restart the Operavix service.

How to Verify ClickHouse Connectivity in Operavix?

ClickHouse connectivity can be verified through the system’s web interface.

To do so:

1. Go to Settings → Data storages.
2. On the opened page, a message displaying the ClickHouse (LimeDB) version should appear in the bottom-right corner.

If the message does not appear, this may indicate a connection issue. Click the Check connection button to perform a forced verification:

• On success: a corresponding notification is displayed.
• On failure: an error message with a description of the problem appears.

For in-depth analysis, refer to the application logs.

Common ClickHouse Connection Errors and Diagnosis

The most frequent ClickHouse connection errors are recorded in the system log files.

Below are key scenarios:

1. Invalid credentials
   • Error: DB::Exception: operavix_user: Authentication failed: password is incorrect, or there is no user with such name. (AUTHENTICATION_FAILED)
   • Resolution: Verify that the username and password are correct and that the user exists in ClickHouse
2. SSL certificate trust failure
   • Error: Check ClickHouse connection fail, cause: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • Resolution: Import the ClickHouse server’s root certificate into the JVM truststore used by Operavix
3. Incorrect SSL configuration
   • Error: Check ClickHouse connection fail, cause: The target server failed to respond
   • Resolution: Confirm that SSL is enabled in the data store settings and that the ClickHouse server is configured to accept HTTPS connections
4. Invalid server address
   • Error: HTTP request failed java.net.UnknownHostException: $server_name: Name does not resolve DEBUG c.i.s.c.u.ClickHouseConnectionUtil:43 - Check ClickHouse connection fail, cause: $server_name: Name does not resolve
   • Resolution: Ensure the server’s DNS name (or IP address) is correct and resolvable from the host where Operavix is running

In all cases, use the Check Connection button and examine system logs for accurate diagnostics:

• Linux: /var/log/operavix/
• Windows: %ProgramData%\Operavix\logs

Technical Requirements and System Architecture

Does the agent impact PC performance? How many resources does it consume?

The monitoring agent is optimized to have minimal impact on workstation performance.

Resource consumption is low:

• RAM: ~15 MB
• CPU: <1% at idle, up to 15% at peak
• Disk & network: minimal usage

What are the server hardware requirements?

Operavix installation requires two main servers:

• Operavix server: 8+ CPU cores, 16+ GB RAM, 60+ GB SSD
• ClickHouse server: 12+ CPU cores, 64+ GB RAM (up to 128 GB recommended for large data volumes), 10+ TB disk space

Technical requirements may vary depending on the number of monitored users.

Which ports does the system use, and what network permissions are required?

Key ports:

• Operavix (web interface): 443 (HTTPS)
• ClickHouse: 8123 (HTTP), 9000 (TCP)
• Monitoring agent: 443 (for data transmission)

These ports must be open between the Operavix server and client machines, as well as between system servers.

Can Operavix be installed in an isolated network without internet access?

Yes, the system can operate in a fully offline, isolated environment.

Installation is performed using standalone Docker containers. The system requires no external connections and runs 24/7 when hardware recommendations are followed.

Which system components are mandatory for installation?

The Operavix application server and ClickHouse server are mandatory; all other components are optional.

Optional components of the architecture:

• Automation Agent — distributes script execution load, especially in large or distributed infrastructures (e.g., for data migration between servers)
• Monitoring Agent on workstations — collects user activity data (applications, actions, screenshots) and sends it to the Operavix server
• Webhook Agent — receives external events from third-party systems (e.g., via integrations) and triggers automation scripts in response (e.g., from Jira, CRM, etc.), extending trigger capabilities
• AI Agent — enables interaction with neural network models for generating analytical widgets, automatic instructions, and other AI-powered features

What technology stack is used? What is the application built on?

The Operavix application is built using: Java SE 21 with Spring MVC, C++, and TypeScript with the React library.

This technology selection ensures:

• High performance of the backend
• Flexibility and scalability of the web interface
• Minimal resource consumption on the client side

How to estimate server load when scaling the number of monitoring agents?

Load increases proportionally to the number of agents and can be assessed via reports and server resource monitoring.

Monitoring and Monitoring Agents

An employee works via terminal, VDI, and a local PC. How is their activity accounted for?

Activity is captured across all devices and merged into a single timeline.

To correctly track employee activity in a hybrid environment (local PCs, terminals, VDI), ensure the following:

• Install the monitoring agent on every device or server used by the employee
• Ensure the employee is unambiguously identified in the system (e.g., by login, ID, email, etc.)

After this, the system:

• Aggregates activity from all devices
• Merges actions into a unified timeline by the employee’s unique ID
• Accounts for switching between devices and accounts (when corresponding rules are configured)

This provides a complete picture of work activity, regardless of access point.

Can the monitoring agent be installed on a terminal server?

Yes, the monitoring agent can be installed on terminal servers (RDS) hosting user sessions.

Agent behavior in terminal environments:

• The agent runs separately in each active user session, ensuring accurate per-user data collection
• The agent process cannot be fully excluded from a session, but data collection can be disabled via monitoring settings for specific users
• Server load scales with the number of concurrent sessions—consider this when sizing hardware
• Agent data (including activity archives) is stored in %AppData%\OperavixAgent\. When using Citrix PVS or similar technologies, ensure user profiles (including %APPDATA%) persist across reconnections

Can specific applications be excluded from monitoring?

Yes, using allowlists and blocklists in monitoring filters.

You can specify which applications and websites to track or ignore. Three application filtering modes are available:

• Allowlist — activity is recorded only for specified apps/sites
• Blocklist — data is collected for all apps/sites except those listed
• Disabled filtering — data is collected for all applications

How do I enable extended monitoring?

You must purchase and assign an extended license.

Extended monitoring is not available by default. To activate it:

• Purchase licenses of Extended Monitoring type
• Assign the license to specific users or groups via the web interface

Licenses can be assigned in two ways:

• Via bulk assignment
• Via a specific user’s profile

Can agent parameters be adjusted to reduce system load?

Yes, individual features can be disabled.

Agent settings allow you to reduce data collection intensity—for example, by disabling screenshot capture.

This helps adapt agent behavior to a specific PC’s performance, minimizing system impact.

How do I enable user activity data collection via the monitoring agent?

After agent installation, activity collection starts automatically. Additional settings (e.g., screenshot capture) are configured via the system interface.

How do I collect monitoring agent logs for troubleshooting?

Agent logs reside on the client machine in:

• Windows: %AppData%\OperavixAgent\logs\
• Linux: ~/.OperavixAgent/logs

Logs can be exported and sent to support.

How does the Operavix Monitoring Agent work?

The monitoring agent consists of two components:

• Agent Service (agent_service.exe). Runs once per machine and handles:
  • Monitoring configuration updates (every 30 minutes)
  • Update checks and installations (hourly)
  • Crash dump uploads (if processes terminate abnormally)
• Agent Inspector (agent_inspector.exe). Runs per active user session and:
  • Collects activity data (applications, actions, screenshots—if advanced monitoring is enabled)
  • Sends data to the Operavix server (if monitoring is enabled for the user)

Data packet size (per 10 minutes): 1–3 KB.
Crash minidumps: ~100 KB (sent hourly).
Required network bandwidth: no less than 256 bytes/s.

Why is data from the monitoring agent not reaching the server?

Possible causes:

• Agent not installed — verify installation on all employee workstations, including VDI and terminal servers
• Service stopped — check the monitoring agent service status in Windows Services and restart if needed
• No network connectivity to server:
  
  • Ensure the server port (443/TCP) is open in firewalls
  • Try accessing the Operavix web interface from the employee’s machine—if it fails, the issue is network-related
• Incorrect server address or API key:
  
  • Server address and API key are set in C:\ProgramData\OperavixAgent\settings.cfg
  • Mismatched keys cause the server to reject data
• Missing FE_URL parameter (v25.3.15+):
  
  • If FE_URL is not set during server deployment, the agent receives localhost and attempts to send data to itself
  • Logs show: URL using bad/illegal format or missing URL

For quick diagnostics, use agent_configurator.exe located in C:\Program Files\OperavixAgent\.

Which monitoring agent files assist in diagnostics?

Key diagnostic files:

What permissions does the monitoring agent require on the client machine?

Standard user privileges are sufficient.

The agent requires only regular user access. Installation needs administrator rights, but runtime operation does not.

Why is the monitoring agent not sending data to the server?

Possible causes:

• Network issues or blocked ports
• Incorrect server configuration
• Agent misconfiguration

Verify connectivity and settings; consult the network diagram for precise troubleshooting.

Does the monitoring agent support HTTP redirects when connecting to the server?

No, the monitoring agent does not support HTTP redirects (status codes 301/302).

If the Operavix server address triggers an HTTP redirect, the agent fails to establish a connection. Errors like syntax error at or near position 0 may appear during installation or operation.

Supported scenarios:

• Reverse proxy (e.g., Nginx, Apache) performing transparent forwarding (no HTTP redirect)
• DNS aliases (CNAME records) pointing to the correct Operavix server host

How do I configure screenshot collection by the monitoring agent?

Screenshot collection is configured in Settings → Screenshot monitoring.

How does user activity collection by the monitoring agent work?

User activity collection involves the following stages:

1. Activity capture by the monitoring agent
2. Archive transmission: Once daily, the agent sends collected data to the Operavix server as archives
3. Reception and initial processing:
   
   • Server stores archives in its internal file database
   • Archives are queued for processing
   • Invalid archives (e.g., malformed manifest.json, unknown user, etc.) are not loaded into ClickHouse and do not appear in monitoring_activity and monitoring_agent_inspector_log tables. These are placed in a corrupted queue and retained on the server
4. ClickHouse synchronization:
   
   • Scheduled via the rdb_ch_synchronization parameter in com.operavix.subsystem.monitoring.json
   • Valid archives are processed and loaded into ClickHouse tables:
     
     • main.monitoring_activity — main user activity
     • main.monitoring_agent_inspector_log — agent technical logs

Why is activity from certain applications not being collected?

The Operavix Agent relies on OS-level accessibility APIs: Microsoft UI Automation (Windows) and AT-SPI (Linux, where applicable).

Data quality, completeness, and agent stability depend on:

• Application compatibility with these accessibility APIs and standards
• Architecture and implementation specifics of third-party apps, including legacy or proprietary systems
• Security policies, third-party protection tools, OS/antivirus restrictions
• Correct interface property exposure by monitored applications
• Proper activation of accessibility technologies (e.g., Java Access Bridge for Java apps)

Operavix implements all reasonable measures to maximize third-party software compatibility but cannot be held responsible for limitations imposed by third-party architectures, API changes, or client infrastructure security policies.

How do I check the current Operavix server and agent versions?

The Operavix server version is displayed in system settings on the About page.

The About page shows versions of all core system components, including the Operavix server.

Can website statistics be collected using Operavix?

Yes—by embedding a JS snippet, configuring data ingestion, and building dashboards in Operavix.

To achieve this, do the following:

1. Insert the JS Tracker snippet (provided in the Operavix UI) into all pages of your website or web app. The snippet loads the tracker to capture events (page views, clicks, form submissions, etc.).
2. Configure data reception. Ensure the Operavix server is accessible. For isolated environments, use the Webhook Agent.
3. Create a processing script. The tracker sends events to Operavix. Create a script with a New Event trigger to process them.
4. Build a dashboard. Store processed data in a Data Model table and visualize it with widgets—enabling analysis of user behavior, conversion funnels, bottlenecks, and campaign effectiveness.

Business Analytics and Dashboards

Can your dashboards be embedded into our website?

Yes, dashboards can be embedded into an external web resource using the HTML <iframe> tag.

To enable this, the administrator must set support_iframe: true in the com.operavix.subsystem.frontend.json configuration file. Once enabled, dashboards can be loaded inside an <iframe>.

After activation, dashboards can be embedded via <iframe>. The dashboard URL—taken from the browser’s address bar—can include filters and variables to customize the displayed view.

How do I create a new dashboard in the BI module?

To build a custom dashboard:

1. Configure the workspace — add tables and define relationships between them
2. Add a dashboard to the workspace and configure data visualization by adding required widgets and filters

How do I export data from a dashboard?

In view mode, tabular reports can be exported:

• As .XLSX via the Download (.xlsx) button
• As .CSV via the Download (.csv) button

.CSV export requires the Component Export privilege.

Why is time displayed in seconds in the exported Excel file, and how can I fix it?

When exporting tabular reports, fields with Duration type are exported in seconds (as integers) to ensure correct re-import into the system.

To display durations in the familiar hh:mm format in Excel:

1. Assume seconds are in column A (e.g., cell A1).
2. In an adjacent cell (e.g., B1), enter the formula:
   =A1/86400
   

   (86400 = seconds in a day)
3. Select the cell → Home → Number → Time.
4. For durations > 24 hours, apply a custom format:
   [hh]:mm
   

5. Drag the formula down to apply it to the remaining rows.

Example: If cell A1 contains 3661, then B1 will display 1:01 (1 hour 1 minute) after formatting.

How do I launch an automated script from a BI dashboard?

• Configure a click action to execute a script
• Set up the action in the following widgets:
  
  • Table
  • Button

Why is the dashboard loading slowly?

This is usually due to complex queries, large data volumes, or an underpowered ClickHouse server.

Optimize your queries and check server load.

How can I view collected screenshots in the Operavix interface?

Screenshots captured by the monitoring agent can be displayed in a dashboard in two ways:

• Using the Text widget
• By configuring a click action

Working with External Data

How do I correctly import CSV files?

To import a table, select Import in the Data Model. The file must include a header row, and no empty rows should be present at the end of the file.

When uploading the table, specify:

• Separator: ; (semicolon), , (comma), | (pipe), / (slash), tab, space, or another character
• Qualifier: ' (single quotes) or " (double quotes)
• Encoding: UTF-8, UTF-8 BOM, or Windows-1251

Why can’t a comma be used as the decimal separator in CSV exports?

The system follows the standard data export format used by the ClickHouse DBMS, where decimal fractions are always separated by a period (.).

This aligns with international standards (ISO/IEC, RFC, JSON, etc.) adopted by most software systems—including databases, programming languages, and analytics tools.

Using a comma as a decimal separator:

• Breaks compatibility with ClickHouse’s internal parsing mechanisms
• Risks incorrect numeric value interpretation (especially during re-import)
• Prevents re-importing an exported CSV file back into Operavix

Therefore, the system intentionally does not support replacing the period with a comma in numeric fields during export.

Does Operavix support import from Excel, JSON, or XML?

Operavix supports CSV files only.

You can prepare data in Excel, Google Sheets, Notepad, or any other editor, but before uploading, save it as CSV. Operavix allows you to configure CSV import parameters.

Direct import from Excel (.xlsx/.xls), JSON, or XML is not supported—data in these formats must be pre-converted to CSV, respecting the required settings.

Task Mining and Process Mining

How are automation and robotization initiatives identified?

The Task Mining report automatically detects repetitive operations and generates optimization recommendations.

How it works:

• Data on typical employee actions is collected
• Repetitive, routine operations are analyzed—e.g., copying data between systems, form filling
• A report with actionable recommendations is generated

The report enables you to:

• Prioritize the most promising cases for optimization
• Estimate the potential impact of proposed changes

How can economic benefits be achieved through Task Mining/Process Mining?

Economic benefits are realized through:

• Labor optimization — by identifying and eliminating routine, non-value-added tasks
• Task automation — Task Mining pinpoints opportunities for robotic process automation (RPA)
• Process cycle time reduction — Process Mining helps locate bottlenecks
• Productivity improvement — via worktime monitoring and identification of best practices across employees
• Data-driven staffing and workload redistribution decisions

Example: If analysis reveals an employee spends two hours daily copying data between systems, this task can be automated—freeing up a full-time equivalent (FTE).

What is the difference between an operation, a process, and a function?

• Operation — An indivisible sequence of steps performed by a single employee, typically within one hour. Examples: Creating a bank client record, managing ledger entries, submitting a purchase request in an information system.
• Function — A set of operations performed by one employee to deliver a single service or complete a task. Examples: Opening a bank account, processing a customer request or ticket.
• Process — A sequence of stages carried out by one or more departments over an extended period—days to months. Examples: Mortgage lending, procurement procedures.

Automation and Process Analysis

Is error logging performed in the Automation module?

Yes, the system maintains detailed logging; errors are recorded in the Execution Log.

Documentation and Consulting

Where can I find up-to-date documentation for Operavix configuration?

Documentation is available on the System Settings page.

Is documentation available in PDF format?

Yes, PDF versions are available for download on the website.

On the Documentation homepage, you can:

• Download a PDF for each section individually—via the download button next to the section title
• Download the entire documentation as a single file—using the Download button at the bottom of the page

How do I use the Operavix GraphQL API?

The Operavix GraphQL API enables queries not available in the web UI and supports automation—e.g., access management.

To create and run GraphQL queries, use the built-in GraphiQL browser IDE: navigate to system_url/graphiql.

For external system integration:

1. Generate an API key in Settings → API Keys
2. Assign the key the required privileges
3. Include the key in requests, e.g.: https://automation-dev.corp.com/graphql?api_key=your_key_here

Where can I find the API documentation?

Full, up-to-date documentation is embedded in the GraphQL interface. Open the Docs tab (top-right of the GraphiQL IDE) to view all available queries and mutations.

How do I configure a Webhook to receive external events?

1. Install and run the Webhook Agent—a standalone Docker module that receives HTTP requests.
2. If requests originate from external domains, configure FE_CORS_POLICY='site1.com,site2.com' in the agent’s settings.
3. Create a script with the New Event trigger from the Webhook package.
4. Once the Webhook Agent forwards the event to Operavix via gRPC, the system automatically executes the script bound to the corresponding trigger.