OPC UA Migration Tutorial: Wrapper and Proxy Configuration Step by Step

4,362

1. Who this tutorial is for, and what you need before you start

This tutorial is written for OT engineers, system integrators, and IT/OT architects who are implementing an OPC UA migration using the Integration Objects OPC UA Wrapper. It covers both migration directions:

OPC Classic servers → OPC UA clients (using the OPC UA Wrapper component)
OPC UA servers → OPC Classic clients (using the OPC UA Proxy component)

If you are still in the planning or business case stage of your OPC UA migration, start with the OPC UA Migration: The Complete Guide for strategy and approach, and the OPC UA Migration Benefits article for the operational case. This tutorial assumes you have already decided to use the Wrapper-based migration approach and are ready to configure it.

What you need before starting

Software:

OPC UA Wrapper installed on a Windows host (download the 30-day free trial to follow along)
An OPC Classic server accessible from the Wrapper host (for Tutorial 1) — this can be any OPC DA, HDA, or AE server; the Integration Objects OPC Server Simulator works well for testing
An OPC UA server accessible from the Proxy host (for Tutorial 2); the Integration Objects OPC UA Server Simulator is a straightforward test target
An OPC UA client for verification (for Tutorial 1); the Integration Objects OPC UA Client is used in the video walkthroughs

Network:

The Wrapper host must be able to reach the OPC Classic server via DCOM (same machine or same local network segment)
The Proxy host must be able to reach the OPC UA server on the OPC UA port (default 4840)
Firewall rules should allow inbound connections to the Wrapper’s OPC UA port from intended OPC UA clients

Permissions:

Administrator rights on the Wrapper host for installation and Windows Service configuration
DCOM permissions configured to allow the Wrapper process to connect to the target OPC Classic server (consult your OPC Classic server’s documentation for DCOM configuration requirements)

2. Understanding the two migration directions

Before starting configuration, it is important to be precise about which direction you are bridging. This is one of the most common sources of confusion when first working with the OPC UA Wrapper product.

The OPC UA Wrapper component solves this problem:

“I have OPC Classic servers (DA, HDA, AE). I want modern OPC UA clients, cloud platforms, new SCADA, analytics tools, to be able to read from them.”

The Wrapper connects to your OPC Classic server via DCOM (inward-facing, legacy side) and presents an OPC UA server interface to external clients (outward-facing, modern side). OPC Classic servers stay unchanged. OPC UA clients see a standard OPC UA server.

The OPC UA Proxy component solves this problem:

“I have new OPC UA servers. I need legacy OPC Classic client applications, older historians, HMIs, reporting tools, to keep connecting to them.”

The Proxy connects to your OPC UA server via OPC UA (inward-facing, modern side) and presents an OPC Classic server interface to legacy clients (outward-facing, legacy side). OPC UA servers stay unchanged. OPC Classic clients see a standard OPC Classic server.

Both components are included in the same OPC UA Wrapper installation and can run simultaneously, making the product suitable for environments where migration is happening in both directions at once.

3. Tutorial 1: Configuring the OPC UA Wrapper (OPC Classic servers → OPC UA clients)

Step 1 – Install the OPC UA Wrapper

Download and run the OPC UA Wrapper installer on your Windows host. The installer registers the Wrapper as a Windows Service, which means it runs in the background without requiring an active user session and survives system reboots automatically.

After installation, open the OPC UA Wrapper Configuration Tool from the Start menu. This is the GUI application used for all Wrapper configuration, you do not need to edit configuration files manually.

Step 2 – Add a Wrapper and configure an OPC Classic server connection

In the Configuration Tool, navigate to the “Wrapper” Home menu and click Add or right click on the “COM to UA” root node and selecting “Add Wrapper”.

The Add Wrapper dialog box will appear, allowing you to enter the name of the wrapper, specify the TCP and HTTPS port numbers, and choose between the machine’s host name or IP address to generate the wrapper URL.

After creating the wrapper, a new node will be added to the COM to UA root node. Right click on the wrapper node and select “Add Servers”.

You will be prompted to browse for available OPC Classic servers on the local machine or network.

Select your target OPC Classic server from the browser. The Wrapper will connect to it and retrieve the server’s available items.

For remote communication, the DCOM configuration is required between the OPC UA Wrapper and the OPC Servers machines. This is a prerequisite of OPC Classic communications.

We generally recommend to install the OPC UA Wrapper on the same OPC DA Server machine in order to avoid DCOM, its configuration and security issues.

Step 3 – Review the automatically generated OPC UA address space

Once connected to the OPC Classic server, the Wrapper automatically maps the server’s tag structure into an OPC UA node hierarchy. This mapping is displayed in the Configuration Tool’s address space view.

By default, the OPC Classic tag hierarchy (e.g., Plant1.Reactor2.Temperature) is preserved as a browseable folder structure in the OPC UA address space. Each OPC Classic item becomes an OPC UA Variable node with the appropriate data type, engineering unit (where available), and access level (read/write based on the OPC Classic item’s access rights).

Review the generated address space and confirm that the structure reflects your expectations. For most OPC DA servers, the automatic mapping requires no manual adjustment. For complex tag hierarchies or where specific OPC UA node naming is required for compatibility with downstream systems, the Configuration Tool provides options to customize node IDs, display names, and folder structure.

Step 4 – Configure OPC UA security

In the Security section of the Configuration Tool, configure the security settings for the OPC UA server interface that the Wrapper will expose to clients.

Security mode: Select Sign & Encrypt for all production deployments. This ensures all OPC UA client connections use encryption and message signing. Only use None in isolated test environments.

Security policy: Select Basic256Sha256 as the preferred policy for secure deployments, as it provides stronger encryption and integrity protection. Avoid Basic128Rsa15 or Basic256 for new configurations unless required for compatibility with older OPC UA clients.

Server certificate: The Wrapper generates a self-signed application instance certificate on first run. You can change the own certificate of the Wrapper with another one (*.pfx).

Trust list: Configure the list of client certificates (or CA certificates) that the Wrapper will accept.. In production, each OPC UA client that connects should have its certificate explicitly added to the Wrapper’s trust list.

Step 5 – Start the Wrapper service and verify

Save the configuration and start (or restart) the OPC UA Wrapper Windows Service from the Configuration Tool or the Windows Services management console.

Open your OPC UA client and browse to the Wrapper’s endpoint (e.g., opc.tcp://[wrapper-host]:48403). Accept the security handshake (add the Wrapper’s certificate to the client’s trust list if it was rejected). Browse the address space and confirm that your OPC Classic tags are visible as OPC UA nodes. Subscribe to one or more nodes and confirm that live data values update correctly.

4. Video walkthrough: OPC UA Wrapper configuration

The video below demonstrates the complete OPC UA Wrapper configuration process, from adding an OPC Classic server to verifying live data in an OPC UA client. The written steps above map directly to the configuration sequence shown in the video.

Watch: How to Configure the OPC UA Wrapper →

The video covers:

Browsing and selecting an OPC Classic DA server
Reviewing the automatically generated OPC UA address space
Configuring OPC UA security mode and certificates
Connecting an OPC UA client to the Wrapper endpoint
Verifying real-time data flow from OPC Classic through to OPC UA

5. Tutorial 2: Configuring the OPC UA Proxy (OPC UA servers → OPC Classic clients)

Step 1 – Open the OPC UA Proxy Configuration Tool

The OPC UA Proxy is configured through the same installation as the Wrapper. Open the OPC UA Proxy Configuration Tool from the Start menu – this is a separate configuration application from the Wrapper tool, focused on the reverse migration direction.

Step 2 – Add an OPC UA server connection

In the Proxy Configuration Tool, navigate to the “Proxy” Home menu and click Add or right click on the “UA to COM” root node and selecting “Add Proxy”.

You can either enter the OPC UA server Endpoint URL (e.g., opc.tcp://[server-host]:4840) or click the Discover button to browse endpoints exposed by OPC UA servers registered with the Local Discovery Server (LDS) on the local machine.

After selecting the security mode, security policy and user authentication mode that the target OPC UA server requires, you can click Apply to proceed to the COM confiugration.

Step 3 – Configure the OPC Classic interface

The Proxy presents itself to legacy OPC Classic clients as an OPC Classic server. Configure the OPC Classic server name and ProgID that legacy clients will use to connect.

This is the identity under which the Proxy will register itself in the Windows OPC server registry, the same registry that OPC Classic clients browse when looking for available servers. Choose a name that is meaningful to the legacy client operators (e.g., “IntegrationObjects.OPCUAProxy.PlantA”).

Step 4 – Configure tag alias mappings

One of the most useful features of the OPC UA Proxy is tag alias configuration – the ability to assign human-readable OPC Classic-style tag names to OPC UA node IDs.

OPC UA node IDs can be verbose and opaque (e.g., ns=2;s=Boiler1/Temperature/ProcessValue). Legacy OPC Classic clients – and more importantly, the operators who configured them, expect short, descriptive tag names (e.g., Boiler1.Temperature). The Proxy’s alias system lets you map any OPC UA node ID to any OPC Classic-compatible tag name, without changing anything in the OPC UA server.

In the Configuration Tool, enable the “Use Alias” chechbox and save the configuration by clicking the “Save” button. When this option is check, you can import alias configuration CSV file using the “Import Alias” option.

You can refer to the tutorial available here on how to configure tag aliases in OPC UA Proxy.

Step 5 – Connect to OPC UA Proxy and verify

The Proxy will now be visible to OPC Classic clients in the local OPC server registry.

Open your OPC Classic client application and browse available OPC servers. The Proxy should appear under its configured name. Connect to it and browse the available items, you should see the aliases you configured in Step 4. Subscribe to items and confirm that live data values from the OPC UA server are reaching the OPC Classic client correctly.

6. Video walkthrough: OPC UA Proxy configuration

The video below demonstrates the complete OPC UA Proxy configuration – from connecting to an OPC UA server to verifying data in a legacy OPC Classic client. The written steps above map directly to the sequence shown in the video.

Watch: How to Configure the OPC UA Proxy →

The video covers:

Adding an OPC UA server connection with security configuration
Browsing the OPC UA server address space
Configuring OPC Classic interface name and ProgID
Setting up tag alias mappings for legacy client compatibility
Connecting an OPC Classic client to the Proxy and verifying data flow

7. OPC UA Wrapper key features reference

The table below summarises the full feature set of the OPC UA Wrapper product, covering both the Wrapper and Proxy components, as a quick reference for configuration planning.

Feature	Wrapper component	Proxy component
OPC DA support	Exposes OPC DA server as OPC UA server – real-time read/write	Exposes OPC UA server as OPC DA server to OPC Classic clients
OPC HDA support	Bridges OPC HDA historical data to OPC UA Historical Access	Not applicable (OPC UA servers expose historical data natively)
OPC AE support	Maps OPC AE alarms and events to OPC UA Alarms and Conditions	Not applicable
Local and remote server connections	Connects to OPC Classic servers on local machine or remote hosts	Connects to OPC UA servers on local machine or remote hosts
Read and write support	Full read/write of OPC DA item values	Full read/write of mapped OPC UA node values
Historical data access	OPC HDA → OPC UA Historical Access bridging	—
Alarm and event bridging	OPC AE → OPC UA Alarms & Conditions mapping	—
Security configuration	OPC UA security mode, policy, and certificate management	OPC UA client security for upstream server connection
Transport protocols	OPC UA TCP (port 4840) and HTTPS (port 4843)	OPC UA TCP and HTTPS for upstream connection
Tag alias mapping	Node ID customisation in OPC UA address space	Friendly OPC Classic tag names for OPC UA node IDs
Windows Service deployment	Runs as Windows background service	Runs as Windows background service
Audit logging	Session, connection, and data operation logging	Session and connection logging
30-day free trial	Available	Available (same installer)

8. After configuration: validating your migration setup

Once both components are configured and running, a structured validation process confirms that data is flowing correctly before transitioning production traffic.

Step 1: Parallel run validation. During initial deployment, keep existing OPC Classic connections active alongside the new Wrapper. Compare values read by an OPC UA client through the Wrapper against values read by an existing OPC Classic client from the same server simultaneously. Values, quality flags, and timestamps should match. Any discrepancy indicates a configuration issue in the address space mapping or data type handling.

Step 2: Security connection test. Attempt to connect to the Wrapper with an OPC UA client using an untrusted certificate. The connection should be rejected. This confirms that the trust list configuration is working correctly and that the Wrapper is not accepting arbitrary connections.

Step 3: Historical data validation (HDA). If the Wrapper is bridging OPC HDA data, query historical values for a known time window through the OPC UA Historical Access interface and compare against the same query made directly to the OPC HDA server. Values and timestamps should match within the precision of the historian.

Step 4: Alarm validation (AE). If the Wrapper is bridging OPC AE alarms, trigger a test alarm condition in the process and confirm that it appears correctly as an OPC UA Alarm and Condition notification at the OPC UA client side.

Step 5: Failover and reconnection test. Stop and restart the OPC Classic server while the Wrapper is running. Confirm that the Wrapper detects the disconnection, logs it appropriately, and reconnects automatically when the OPC Classic server restarts, without requiring a Wrapper service restart.

9. Common configuration issues and how to resolve them

OPC Classic server not appearing in the browser. The most common cause is DCOM permissions. The Windows account running the OPC UA Wrapper service must have DCOM activation and access permissions for the target OPC Classic server. Open DCOMCNFG (Component Services) on the machine hosting the OPC Classic server and verify that the Wrapper service account has the required permissions. If the OPC Classic server is on a remote machine, also verify that Windows Firewall on the remote machine permits DCOM traffic from the Wrapper host.

OPC UA client cannot connect to the Wrapper endpoint. Check that the OPC UA Wrapper Windows Service is running. Verify that the Windows Firewall on the Wrapper host allows inbound connections on the configured OPC UA port (default 4840). Confirm that the OPC UA client is attempting to connect to the correct hostname or IP address and port. If using certificate authentication, verify that the client’s certificate is in the Wrapper’s trust list and that the Wrapper’s certificate is in the client’s trust list.

OPC UA client connection is rejected with “certificate not trusted” error. This is the expected behaviour when a client presents a certificate that is not in the Wrapper’s trust list. Open the Wrapper Configuration Tool, navigate to the Trust List section, and add the client’s certificate. If testing with the Auto-accept option, confirm it is enabled, but remember to disable it before production deployment.

Data values in OPC UA client show “Bad” quality. A Bad quality flag from the Wrapper typically indicates that the underlying OPC Classic server is returning bad quality for those items. The Wrapper accurately reflects the OPC Classic quality in the OPC UA quality code. Verify the data quality in a direct OPC Classic client connection. If the OPC Classic client shows Good quality but the OPC UA client shows Bad, check the data type mapping configuration in the Wrapper address space, a type mismatch can cause quality degradation on the OPC UA side.

Legacy OPC Classic client cannot see the Proxy in the server browser. Confirm that the OPC UA Proxy Windows Service is running. The Proxy registers itself in the Windows OPC server registry on startup. If the Proxy service is running but the client cannot see it, verify that the Proxy’s ProgID is correctly registered by checking the Windows registry under HKEY_LOCAL_MACHINE\SOFTWARE\Classes for the Proxy’s configured ProgID. On 64-bit Windows, also check HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Classes for 32-bit OPC Classic clients.

Tag aliases not appearing correctly in OPC Classic client. Confirm that aliases are saved in the Proxy Configuration Tool and that the Proxy service has been restarted after saving alias changes. Aliases are loaded at service startup. Changes to the alias configuration require a service restart to take effect. Verify that the alias names do not contain characters that are invalid in OPC Classic item IDs (some OPC Classic clients reject tag names containing spaces or special characters).