> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/reference/functions/connectors/opc-ua-client.md).

# OPC UA client

Learn how to connect to an OPC UA server using the Heisenware OPC UA client.

The OPC UA client connector (`OpcuaClient`) communicates with OPC UA servers. It manages secure connections, browses the server's address space, reads and writes variables, calls methods, monitors single nodes or whole parameter sets for changes, and transfers files.

This connector requires [instance creation](https://docs.heisenware.com/reference/functions/connectors.md#instance-creation) before you can manage the connection and session with a server. For secure connections, generate certificates using `createCertificates`.

{% hint style="info" %}
See the [Video demo](#video-demo) at the bottom of this page.
{% endhint %}

## Security and certificates

{% hint style="info" %}
For unencrypted connections, skip directly to [Connection and lifecycle](#connection-and-lifecycle).
{% endhint %}

Secure OPC UA communication (`Sign` or `SignAndEncrypt`) requires a Public Key Infrastructure (PKI) to manage digital certificates and establish trust between the client and the server. Only create a PKI store when connecting with a `securityMode` of `Sign` or `SignAndEncrypt`. For unsecured connections, you can ignore certificate management.

### Self-signed and CA-signed certificates

`createCertificates` prepares the client for secure connections in one of two modes:

* **Self-signed (default)**: The client creates its own certificate without a signature from a certificate authority. This is the simplest approach and works best for most scenarios.
* **CA-signed (set `useCA` to `true`)**: The client creates its own Certificate Authority (CA) to sign the application and user certificates. Use this if the server trusts a single CA instead of multiple individual client certificates.

### Establishing trust

OPC UA security requires a two-way trust model:

* **The server trusts the client**: Configure the server to accept the client's public certificate.
* **The client trusts the server**: Add the server's public certificate with `addServerCertificate`. It lands in the workspace's [Trusted certificates](https://docs.heisenware.com/reference/functions/connectors/trusted-certificates.md), the one list every connector consults.

Manage this process using `createCertificates` and `addServerCertificate`.

### Client PKI folder structure

`createCertificates` generates a standard `pki` folder structure:

* `pki/own/certs/`: The client's public certificates (for example, `heisenware_opcua_client.pem`). Provide this file to the server administrator.
* `pki/own/private/`: The client's private keys. Keep these keys secret. The client automatically restricts access permissions.
* `pki/trusted/certs/`: The trusted servers, shared with every connector as [Trusted certificates](https://docs.heisenware.com/reference/functions/connectors/trusted-certificates.md). `addServerCertificate` puts a server's certificate here.
* `pki/issuers/certs/`: The trusted authorities. In CA mode, this folder also holds the client's own CA. If a company CA signed the server certificate, add it with `addCertificateAuthority`.

{% hint style="info" %}

#### PKI store location

The location of the `pki` folder depends on where the client runs:

* **Native agent**: `pki` in the directory the agent is started from, which is the directory of the executable when you start it from there.
* **Platform**: `/shared/certificates/pki`. Click the refresh icon in the [Files explorer](https://docs.heisenware.com/app-builder/app-builder/files.md) to view it.
  {% endhint %}

## Certificate management

These static functions manage secure connection setup.

### `createCertificates`

Initializes the local PKI store and creates a client certificate for the application and a user certificate for authentication. By default, this function creates self-signed certificates. Run this function once. Existing certificates are kept on repeated runs.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>useCA</code></td><td>Creates a local Certificate Authority to sign the certificates. Default false.</td><td>boolean</td></tr></tbody></table>

#### Output

Returns `true` when the PKI structure and certificates are successfully created.

### `addServerCertificate`

Trusts one OPC UA server by its certificate, for a secure connection. The certificate is what the server shows in its own settings, usually available as a file there. The server lands in the workspace's [Trusted certificates](https://docs.heisenware.com/reference/functions/connectors/trusted-certificates.md), so every connector accepts it from then on; `TrustStore.list` shows what is trusted, `TrustStore.remove` takes it out again.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>certificate</code></td><td>The server's certificate as text (<code>-----BEGIN CERTIFICATE-----</code> ...) or the path to a certificate file (PEM or DER).</td><td>string</td></tr><tr><td><code>name</code></td><td>A name for the stored certificate. Optional, taken from the file name or the certificate itself when omitted.</td><td>string</td></tr></tbody></table>

#### Output

What is trusted now: `{ name, kind, subject, issuer, selfSigned, validFrom, validTo, fingerprint }`. A file or text that is not a certificate is refused with the reason.

#### Examples

**Example 1: Add a certificate from a file**

{% hint style="info" %}
If the client runs on the platform and not on an agent, upload the server certificate with the [Files explorer](https://docs.heisenware.com/app-builder/app-builder/files.md), drag the file to this parameter, and then delete it from the uploads folder.
{% endhint %}

```yaml
# certificate
/shared/uploads/machine-server.der
```

**Example 2: Add a certificate from a string**

```yaml
# certificate
'-----BEGIN CERTIFICATE-----\nMIIC...etc...\n-----END CERTIFICATE-----'
# name
machine-server
```

### `addCertificateAuthority`

Trusts every server whose certificate was issued by this authority. Use it when the servers carry certificates your company made: add the company's certificate once, and all of them are trusted. Same list as `addServerCertificate`, shared by every connector.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>certificate</code></td><td>The authority's certificate as text or the path to its file (PEM or DER).</td><td>string</td></tr><tr><td><code>name</code></td><td>A name for the stored certificate. Optional, taken from the file name or the certificate itself when omitted.</td><td>string</td></tr></tbody></table>

#### Output

What is trusted now, as for `addServerCertificate`, with `kind: authority`.

## Connection and lifecycle

### `create`

Creates an OPC UA client instance. The security settings determine how the client connects.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>securityMode</code></td><td>The security mode to use (<code>None</code>, <code>Sign</code>, or <code>SignAndEncrypt</code>). Default <code>None</code>.</td><td>string</td></tr><tr><td></td><td><code>securityPolicy</code></td><td>The encryption algorithm to use (such as <code>Basic256Sha256</code>). Default <code>None</code>.</td><td>string</td></tr><tr><td></td><td><code>automaticallyAcceptUnknownCertificate</code></td><td>Disables server validation. Default false.</td><td>boolean</td></tr></tbody></table>

{% hint style="danger" %}

#### Security risk

Never set `automaticallyAcceptUnknownCertificate` to `true` in production. This disables server validation and exposes the system to man-in-the-middle attacks. Use it for debugging purposes only.
{% endhint %}

#### Output

Returns the name of the created instance.

#### Examples

**Example 1: Create a client for an unsecured connection**

```yaml
# (No arguments needed)
```

**Example 2: Create a client for a secure connection**

```yaml
# options
securityMode: SignAndEncrypt
securityPolicy: Basic256Sha256
```

### `connect`

Connects to an OPC UA server. If a secure connection fails, see [Tips and tricks](#tips-and-tricks) for troubleshooting the chain of trust.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>endpointUrl</code></td><td></td><td>The full URL of the server endpoint (such as <code>opc.tcp://my-server.com:4840</code>).</td><td>string</td></tr><tr><td><code>userIdentity</code></td><td><code>username</code></td><td>The username for authentication.</td><td>string</td></tr><tr><td></td><td><code>password</code></td><td>The password for authentication.</td><td>string</td></tr><tr><td></td><td><code>userCertificate</code></td><td>The user certificate for certificate-based authentication.</td><td>string</td></tr><tr><td></td><td><code>userPrivateKey</code></td><td>The private key belonging to the user certificate.</td><td>string</td></tr><tr><td></td><td><code>useDefaultUserCertificate</code></td><td>Set to <code>true</code> to authenticate with the user certificate created by <code>createCertificates</code>. Default false.</td><td>boolean</td></tr></tbody></table>

#### Output

Returns `true` when the connection succeeds or the client is already connected. Returns the string `reconnect ongoing` if an automatic reconnection is in progress. Throws an error on failure.

#### Examples

Each scenario shows the inputs of both `create` and `connect`.

**Example 1: Unsecured, anonymous connection**

Requires no PKI setup and no user identity.

```yaml
# (In create)
# (No arguments)

# (In connect)
# endpointUrl
opc.tcp://my-server.com:4840
```

**Example 2: Secure, anonymous connection**

Requires the PKI setup (`createCertificates` and `addServerCertificate`) but no user identity.

```yaml
# (In create)
# options
securityMode: SignAndEncrypt
securityPolicy: Basic256Sha256

# (In connect)
# endpointUrl
opc.tcp://my-secure-server.com:4840
```

**Example 3: Secure connection with username and password**

Requires the PKI setup for a secure channel, plus credentials for user authentication.

```yaml
# (In create)
# options
securityMode: SignAndEncrypt
securityPolicy: Basic256Sha256

# (In connect)
# endpointUrl
opc.tcp://my-secure-server.com:4840
# userIdentity
username: myuser
password: mysecretpassword
```

**Example 4: Secure connection with a user certificate**

The most secure method, using certificates for both channel security and user authentication.

```yaml
# (In create)
# options
securityMode: SignAndEncrypt
securityPolicy: Basic256Sha256

# (In connect)
# endpointUrl
opc.tcp://my-secure-server.com:4840
# userIdentity
useDefaultUserCertificate: true
```

### `disconnect`

Disconnects from the OPC UA server and closes the active session. Every `monitorNode` and `monitorVariable` registration ends with it: the monitored items live in the session. Connect again and trigger the monitoring executors again.

#### Parameters

None.

#### Output

Returns `true` on successful disconnection, including when no connection exists.

### `isConnected`

Checks whether the client is connected to the server.

#### Parameters

None.

#### Output

Returns `true` if connected, or `false` if disconnected.

### `delete`

Removes the client instance and closes the connection.

{% hint style="danger" %}

#### Irreversible action

Deleting an instance removes its configuration. To communicate with the server again, you must create a new instance.
{% endhint %}

#### Parameters

None.

#### Output

Returns `true` upon removal.

## Browsing

### `browse`

Browses a node address on the server.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td>The <code>nodeId</code> or browse path (such as <code>/0:Objects/2:Demo</code>) where browsing starts.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of objects representing each node found, including its name, ID, and class.

#### Example

```yaml
# address
/0:Objects/2:Demo
```

### `browseObjects`

Browses the server's Objects folder.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>path</code></td><td>An optional browse path starting inside the Objects folder, or a <code>nodeId</code>. Browses the Objects folder itself if omitted.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of objects representing each node found.

#### Example

```yaml
# path
2:Demo/2:Dynamic/2:Scalar
```

### `browseTypes`

Browses the server's Types folder to explore the data type hierarchy.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>path</code></td><td>An optional browse path starting inside the Types folder.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of objects representing each node found.

#### Example

```yaml
# path
0:BaseObjectType/0:FolderType
```

### `browseViews`

Browses the server's Views folder.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>path</code></td><td>An optional browse path starting inside the Views folder.</td><td>string</td></tr></tbody></table>

#### Output

Returns an array of objects representing each node found.

#### Example

```yaml
# path
0:Server
```

## Reading and writing

`readNode` and `readVariable` take a single address or a list of addresses. A list goes to the server in as few requests as it allows, so a machine's whole parameter set is one read instead of one read per value. The result then holds one object per address, in the order given, carrying the address and the node id next to the value: `{ address, nodeId, value }`.

### `readNode`

Reads one or many OPC UA nodes as full data values: the value with its data type, the status code, and the timestamps.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td>The <code>nodeId</code> or browse path of the node to read, or a list of them.</td><td>string or array</td></tr></tbody></table>

#### Output

For a single address, a JSON object containing the node's attributes, status code, and timestamps. For a list, one `{ address, nodeId, value }` per address, `value` being that object. A node the server cannot read, or a browse path it cannot resolve, stands in the result with its status code and fails nothing else.

```json
{
  "value": {
    "dataType": "Int32",
    "value": 12345
  },
  "statusCode": {
    "name": "Good",
    "value": 0
  },
  "serverTimestamp": "2025-07-11T08:52:34.000Z",
  "sourceTimestamp": "2025-07-11T08:52:34.000Z"
}
```

#### Examples

**Example 1: Read using a nodeId**

```yaml
# address
ns=2;s=Demo.Dynamic.Int32
```

**Example 2: Read using a browse path**

```yaml
# address
/0:Objects/2:Demo/2:Dynamic/2:Int32
```

### `readVariable`

Reads the value of one or many variables from the server.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td>The <code>nodeId</code> or browse path of the variable to read, or a list of them.</td><td>string or array</td></tr></tbody></table>

#### Output

For a single address, the raw value of the variable. For a list, one `{ address, nodeId, value }` per address. A variable the server answers with a bad status code, an unknown node id for one, fails the whole read and the error names every such address with its status. Use `readNode` where you want each node's status instead.

#### Examples

**Example 1: Read using a nodeId**

```yaml
# address
ns=2;s=Demo.Dynamic.Int32
```

**Example 2: Read using a browse path**

```yaml
# address
/0:Objects/2:Demo/2:Dynamic/2:Int32
```

**Example 3: Read a machine's parameter set in one request**

```yaml
# address
- ns=2;s=Demo.Dynamic.UInt16
- ns=2;s=Demo.Dynamic.Int32
- /0:Objects/2:Demo/2:Dynamic/2:Double
```

### `writeVariable`

Writes a new value to a server variable. Converts the value to the variable's OPC UA data type before writing; enumerations and other custom data types are written as their built-in base type. If the variable is read-only or holds a structured value, this function throws an error.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td></td><td>The <code>nodeId</code> or browse path of the variable.</td><td>string</td></tr><tr><td><code>value</code></td><td></td><td>The new value to set.</td><td>any</td></tr><tr><td><code>options</code></td><td><code>skipTypeChecking</code></td><td>If <code>true</code>, the client skips reading metadata and permissions before writing. Default false.</td><td>boolean</td></tr></tbody></table>

#### Output

Returns nothing on a successful write. Throws an error on failure.

#### Example

```yaml
# address
ns=2;s=Demo.Dynamic.Int32
# value
42
```

### `callMethod`

Invokes a method on an OPC UA object.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>methodAddress</code></td><td>The <code>nodeId</code> or browse path of the method to call.</td><td>string</td></tr><tr><td><code>inputValues</code></td><td>An array of input arguments; a single value is taken as the one argument. The client infers each argument's data type from the method's metadata on the server. Default [].</td><td>array or any</td></tr></tbody></table>

#### Output

Returns an array containing the output arguments from the method call. Throws an error if the number of input values does not match the method definition or the call fails.

#### Example

```yaml
# methodAddress
ns=2;s=Demo.Methods.Multiply
# inputValues
  - 5
  - 10
```

## Monitoring

Monitoring subscribes to changes on the server and delivers them to a callback. `monitorNode` and `monitorVariable` accept a single address or a list of addresses. A list is registered with a single server request (split only where the server limits the number of items per request), so a machine's whole parameter set fits into one block, and every change of a listed node arrives tagged with the address it belongs to.

{% hint style="info" %}
Monitoring a node that is already monitored reuses the existing subscription and never registers the callback twice, so you can extend a list and run the block again. Nodes that are already monitored keep their original options.
{% endhint %}

Both are event functions. Every listener is greeted with the current value of each of its nodes before the first change arrives, also of a node someone else monitors already, so a page shows values without waiting. Monitoring ends when the executor's [subscription](https://docs.heisenware.com/concepts/backend-events.md) ends, when `stopMonitor` takes one of its items away, when the instance disconnects or when the server drops the subscription; the executor's status then says so. **Stop listening** in the menu of its event input ends it until the next trigger.

### `monitorNode`

Subscribes to changes of one or many OPC UA nodes. Triggers the callback on every change.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td></td><td>The <code>nodeId</code> or browse path of the node, or a list of them.</td><td>string or array</td></tr><tr><td><code>listener</code></td><td></td><td>Callback evaluated on every change. For a single address it receives a JSON object containing the node's <code>dataType</code> and <code>value</code>. For a list it receives <code>{ address, nodeId, value }</code>, where <code>value</code> is that object and <code>address</code> is the entry of your list the change belongs to.</td><td>callback</td></tr><tr><td><code>options</code></td><td><code>samplingInterval</code></td><td>How often the server checks for changes, in milliseconds. Default 1000.</td><td>integer</td></tr><tr><td></td><td><code>queueSize</code></td><td>Maximum number of queued notifications on the server. Default 100.</td><td>integer</td></tr><tr><td></td><td><code>discardOldest</code></td><td>If <code>true</code>, drops the oldest notification when the queue is full. Default true.</td><td>boolean</td></tr></tbody></table>

#### Output

The return is the resolved `nodeId`, or for a list the `nodeId`s in the order of the list; use them with `stopMonitor`. It says no more than that the executor is listening: the changes arrive on the event outputs. A list is all-or-nothing: if an address does not resolve or the server refuses a node, nothing is monitored and the error names every failing address.

#### Examples

**Example 1: Monitor a single node**

```yaml
# address
ns=2;s=Demo.Dynamic.UInt16
# listener
<callback>
# options
samplingInterval: 5000
```

**Example 2: Monitor a list of nodes**

```yaml
# address
- ns=2;s=Demo.Dynamic.UInt16
- ns=2;s=Demo.Dynamic.Int32
- /0:Objects/2:Demo/2:Dynamic/2:Double
# listener
<callback>
```

Every change then reaches the callback as one object:

```json
{
  "address": "/0:Objects/2:Demo/2:Dynamic/2:Double",
  "nodeId": "ns=2;s=Demo.Dynamic.Double",
  "value": {
    "dataType": "Double",
    "value": 3.14
  }
}
```

### `monitorVariable`

Subscribes to value changes of one or many variables. Triggers the callback with the new value on every change.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td></td><td>The <code>nodeId</code> or browse path of the variable, or a list of them.</td><td>string or array</td></tr><tr><td><code>listener</code></td><td></td><td>Callback evaluated on every change. For a single address it receives the raw value of the variable. For a list it receives <code>{ address, nodeId, value }</code>, where <code>value</code> is the raw value and <code>address</code> is the entry of your list the change belongs to.</td><td>callback</td></tr><tr><td><code>options</code></td><td><code>samplingInterval</code></td><td>How often the server checks for changes, in milliseconds. Default 1000.</td><td>integer</td></tr><tr><td></td><td><code>queueSize</code></td><td>Maximum number of queued notifications on the server. Default 100.</td><td>integer</td></tr><tr><td></td><td><code>discardOldest</code></td><td>If <code>true</code>, drops the oldest notification when the queue is full. Default true.</td><td>boolean</td></tr></tbody></table>

#### Output

The return is the resolved `nodeId`, or for a list the `nodeId`s in the order of the list; use them with `stopMonitor`. It says no more than that the executor is listening: the changes arrive on the event outputs. A list is all-or-nothing: if an address does not resolve or the server refuses a node, nothing is monitored and the error names every failing address.

#### Examples

**Example 1: Monitor a single variable**

```yaml
# address
ns=2;s=Demo.Dynamic.UInt16
# listener
<callback>
# options
samplingInterval: 5000
```

**Example 2: Monitor a machine's parameter set**

```yaml
# address
- ns=2;s=Demo.Dynamic.UInt16
- ns=2;s=Demo.Dynamic.Int32
- /0:Objects/2:Demo/2:Dynamic/2:Double
# listener
<callback>
# options
samplingInterval: 500
```

Every change then reaches the callback as one object, ready to be routed by `nodeId` or `address`:

```json
{
  "address": "ns=2;s=Demo.Dynamic.Int32",
  "nodeId": "ns=2;s=Demo.Dynamic.Int32",
  "value": 42
}
```

### `stopMonitor`

Stops monitoring one or many items. Accepts whatever `monitorNode` and `monitorVariable` accept or return: `nodeId`s, browse paths, or a list of them. Items that are not monitored are ignored.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td>The <code>nodeId</code> or browse path of the item, or a list of them.</td><td>string or array</td></tr></tbody></table>

#### Output

Returns `true` once the items are no longer monitored.

#### Examples

**Example 1: Stop a single item**

```yaml
# address
ns=2;s=Demo.Dynamic.UInt16
```

**Example 2: Stop a list of items**

```yaml
# address
- ns=2;s=Demo.Dynamic.UInt16
- ns=2;s=Demo.Dynamic.Int32
```

## File transfer

### `browseDirectory`

Recursively browses a directory structure on the server.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td>The <code>nodeId</code> or browse path of the directory node.</td><td>string</td></tr></tbody></table>

#### Output

Returns the directory's entries as `{ id, name }`. A folder among them carries its own entries as `children`, so one call describes the whole tree below the node.

### `readFile`

Reads the contents of a file on the server.

#### Parameters

<table><thead><tr><th width="150">Input</th><th width="120">Key</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>address</code></td><td></td><td>The <code>nodeId</code> or browse path of the file.</td><td>string</td></tr><tr><td><code>options</code></td><td><code>encoding</code></td><td>The encoding of the returned content (such as <code>ascii</code> or <code>utf8</code>). Default <code>base64</code>.</td><td>string</td></tr></tbody></table>

#### Output

Returns the file content as a string in the requested encoding.

#### Example

```yaml
# address
ns=2;s=Demo.Files.TextFile
```

### `writeFile`

Creates a file on the server and uploads content to it.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>folderAddress</code></td><td>The <code>nodeId</code> or browse path of the target folder.</td><td>string</td></tr><tr><td><code>newFileName</code></td><td>The name of the new file.</td><td>string</td></tr><tr><td><code>pathOrBase64</code></td><td>The file content, specified as a base64 string or local file path.</td><td>string</td></tr></tbody></table>

#### Output

Returns the `nodeId` of the file written to. A file of that name that exists already is reused, not created a second time.

#### Example

```yaml
# folderAddress
ns=2;s=Demo.Files
# newFileName
report.txt
# pathOrBase64
SGVsbG8sIFdvcmxkIQ==
```

### `deleteFile`

Deletes a file on the server.

{% hint style="danger" %}

#### Irreversible action

Deleting a file permanently removes it from the server. This action cannot be undone.
{% endhint %}

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>folderAddress</code></td><td>The <code>nodeId</code> or browse path of the folder containing the file.</td><td>string</td></tr><tr><td><code>fileName</code></td><td>The name of the file to delete.</td><td>string</td></tr></tbody></table>

#### Output

Returns `true` when the file is successfully deleted, or `false` if the deletion fails or the folder provides no delete capability. Throws an error if the file cannot be found.

#### Example

```yaml
# folderAddress
ns=2;s=Demo.Files
# fileName
report.txt
```

## Event listeners

### `listenToEvents`

Registers a callback to receive client lifecycle events.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>listener</code></td><td>Callback evaluated on client lifecycle events. Receives one of the following event strings: <code>Connected</code>, <code>Connection Failed</code>, <code>Connection Lost</code>, <code>Started Reconnection</code>, <code>Connection Re-Established</code>, <code>Back Off</code>, <code>Security Token Renewed</code>, <code>Request Timed Out</code>, <code>Session Closed</code>, <code>Subscription Started</code>, <code>Subscription Keep Alive</code>, <code>Subscription Terminated</code>.</td><td>callback</td></tr></tbody></table>

#### Output

Returns the listener's registration, which only says that the executor is listening. The event strings arrive on the event output.

## Deprecated functions

The following functions are maintained for backward compatibility. Update your App logic to use the recommended replacements.

| Deprecated function  | Use instead     |
| -------------------- | --------------- |
| `readVariableValue`  | `readVariable`  |
| `writeVariableValue` | `writeVariable` |

## Tips and tricks

Establishing a secure certificate-based connection is the primary point of failure in OPC UA. An error usually indicates a broken link in the chain of trust. Use these troubleshooting steps to resolve common issues.

### Switch an existing instance to a secure connection

To switch an unsecured instance to a secure connection, remove the instance and create it again. Right-click the existing active instance (green in the UI), click **Remove**, and the instance turns yellow to indicate it is not available. Trigger the `create` function again to apply your new security configuration.

### Server rejects the client certificate

If the client attempts to connect and the server immediately closes the connection (often showing an error such as `The connection has been disconnected by third party`), the server does not trust the client's application certificate.

To resolve this (using Prosys Simulation Server as an example):

1. Attempt to connect the client to the Prosys server. This fails but registers the client's certificate with the server.
2. Open the **Certificates** tab in the Prosys Simulation Server UI.
3. Locate the client certificate (`HeisenwareOPCUAClient`) in the **Rejected Certificates** list.
4. Right-click the certificate and select **Trust** to move it to the **Trusted Certificates** list.
5. Connect again.

In CA mode, add the CA's public certificate (`heisenware_ca_cert.pem`) to the server's PKI issuers directory (`pki/CA/issuers/certs/`) instead of trusting individual certificates.

### Client rejects the server certificate

If the client does not trust the server, it fails with the error `server Certificate verification failed`.

To resolve this, add the server's public certificate to the client's trust store:

1. Export the server's public certificate file (such as exporting from the Prosys **Certificates** tab).
2. Use `addServerCertificate` to save the file to the client's `pki/trusted/certs` folder.

### SAN mismatch

Even with established trust, the client rejects the connection if the hostname in the endpoint URL does not match any address in the server certificate's Subject Alternative Name (SAN) field.

To resolve this (using Prosys as an example):

1. If connecting to `opc.tcp://localhost:53530` fails, inspect the certificate. If the SAN field only lists `DNS:lenovo`, you must match that hostname.
2. Update the endpoint URL to use the correct hostname, such as `opc.tcp://lenovo:53530/OPCUA/SimulationServer`.

### Certificate revocation list failures

If a server certificate points to a Certificate Revocation List (CRL), the client attempts to download this list to verify validity. In isolated networks without internet access, this lookup fails and blocks the connection.

To resolve this, download the CRL file manually and place it in the client's `pki/issuers/crl` or `pki/trusted/crl` folder. If you generated the server certificate with a custom CA, you can create an empty CRL file to satisfy this check.

### Application and user authentication

These two certificate types serve distinct purposes:

1. **Application certificate (`heisenware_opcua_client.pem`)**: Identifies the application to establish the secure, encrypted channel between client and server. This is mandatory for secure connections.
2. **User certificate (`heisenware_opcua_user.pem`)**: Identifies the user to handle authentication and permissions after the secure channel is established. This is optional.

User certificate authentication requires server-side configuration. The server administrator must create the user account and map it explicitly to the user's public certificate. For Prosys Simulation Server, this feature is only available in the Professional Edition.

### Server and client clocks out of sync

OPC UA blocks secure connections if the clocks of the client and server differ substantially (for example, by an hour). When this occurs, the client logs a warning.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/reference/functions/connectors/opc-ua-client.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
