Configure the File Connector

Configure the File Connector to read or write files in local storage or on an FTP/SFTP server.

+ More

The File Connector reads files from local storage or an FTP/SFTP server and returns their contents as structured JSON. It can also collect values received through mappings, build a file, and save the completed file locally or upload it to an FTP/SFTP server.

This guide explains how to configure an instance and item, choose when a file is completed, read supported file content, and troubleshoot common problems.

Before you begin

Install the File Connector.
Decide whether the files will be stored locally or on an FTP/SFTP server.
For remote storage, obtain the server URL, username, password, and directory information.
For writing, decide what each mapped value should add to the file and when the Connector should complete the file.
For reading, confirm the filename, directory, and file structure.

Use a unique filename when files must be retained. When a completed local file has the same path and filename as an existing file, the existing file is replaced. The default filename includes a timestamp to help prevent this.

Choose local or remote file storage

Storage	Address setting	Result
Local	Leave Address empty.	The Connector reads from and writes to its managed local file storage.
FTP	Enter a URL beginning with `ftp://`.	The Connector downloads from or uploads to the FTP server.
SFTP	Enter a URL beginning with `sftp://`.	The Connector downloads from or uploads to the SFTP server.

For remote files, the Connector combines Address, Root directory, File directory, and Filename to create the complete file location.

Create a File instance

In the Edge Portal, select Workspace > Instances.
Select Add instance.
Select the File Connector.
Enter a name for the instance.
Configure the instance parameters.
Select Create.

Parameter	Description
Address	Leave empty for local storage, or enter the FTP/SFTP server URL beginning with `ftp://` or `sftp://`.
Username	Username used to access the FTP/SFTP server. Leave empty for local storage.
Password	Password used to access the FTP/SFTP server. Leave empty for local storage.
Root directory	Base directory that contains the files on the selected storage destination.

Create a File item

Open the File instance.
Select the Items tab.
Select Add item.
Enter an item name.
Configure the item parameters.
Select Create.

Parameter	Description
Filename	Name of the file to read or write. The default value is `defaultFileName_%TIME.FORMAT("yyyy-MM-ddTHH-mm-ss")%.csv`.
Header	Controls whether the first row of a CSV file is treated as column names when the file is read. Select No header or First line is header.
Prepend	Content written once at the beginning of a new output file. The default is `ItemName,Value,Timestamp`.
Separator	Characters added after each written value.
Appendix	Content written once at the end of a file when it is completed.
Upload type	Determines when the current file is completed. Available options are Time, Data samples, File size, and Flush with mapping.
Upload parameter	Limit or command used by the selected upload type.
File directory	Directory below the instance root directory that contains the file.

Write a file

Create a mapping whose destination is the File item. Each value received by the item is written as a data line. Use the mapping expression to produce the text or structured line required by the destination file.

When a new output file is started, the Connector writes the configured Prepend content first. It then writes incoming values. When the completion condition is reached, it adds the Appendix content and finalizes the file.

The Connector recognizes the literal escape sequences \n, \t, and \r in file formatting fields when they are processed.

Choose when to complete the file

Upload type	Upload parameter	Behavior
Time	Number of minutes	The file is completed when a new value arrives after the configured time has elapsed. The Connector does not run a separate background timer.
Data samples	Number of samples	The file is completed when it reaches the configured number of written samples.
File size	Size in kB	The limit is evaluated when a value is written. The final file can be slightly larger than the configured size.
Flush with mapping	Command text	The file is completed when the item receives the configured command. `FLUSH` and `WRITE` are also recognized. The command itself is not written to the file.

For local storage, the completed file is moved to the Connector's managed file storage. For FTP/SFTP, the Connector uploads the file and attempts to create missing server directories. If the upload fails, the completed file is retained in local storage.

To view and manage completed local files, see Manage and configure Connector files and certificates.

Read a file

When the File item is read, the Connector locates the configured file and returns one JSON-formatted value. For FTP/SFTP, it first downloads the remote file to temporary local storage.

Detected content	Parser value	Returned data
Valid XML	`xml`	The converted XML structure is returned in `content`. Attributes become properties and repeated elements become arrays.
Comma- or semicolon-separated text	`csv`	Rows are returned in `rows`. With a header, the column names become property names. Without a header, the properties are named `row0`, `row1`, and so on.
Other text	`generic`	Each line is returned as a string in `rows`.

The returned JSON also includes filename and parser.

CSV requirements

The Connector detects CSV content from commas or semicolons in the first line.
It uses the delimiter that appears most often in the first line. If the counts are equal, it uses a comma.
When First line is header is selected, the header is not returned as a data row.
Every data row must contain the same number of fields as the header.
The current parser performs a simple delimiter split. Delimiters inside quoted fields are not treated specially.

Verify the configuration

Verify writing

Send test values to the File item through its mapping.
Meet the configured completion condition.
For local storage, confirm that the completed file appears in the Connector files.
For FTP/SFTP, confirm that the file appears at the expected server path.
Open the file and verify the prepend content, written values, separators, and appendix.

Verify reading

Place a test file at the configured local or remote location.
Read the File item.
Confirm that the returned value contains the expected filename, parser, and file content.
For CSV content, verify the property names and number of fields in each row.

Troubleshoot the File Connector

Message or symptom	Cause and action
`Could not resolve server address. FTP server URL has to begin with "ftp://" or "sftp://"`	The non-empty Address does not use a supported prefix. Correct the URL, or clear the field to use local storage.
`Missing Field: No filename for item`	Filename is empty. Enter the file name and save the item.
`Missing Field: No File format for item`	The item received an empty value while writing. Check the source item and mapping expression.
`File not found (...) or empty`	The file does not exist at the constructed path or contains no data. Check the address, root directory, file directory, filename, capitalization, and access permissions.
CSV file has an invalid format or unequal elements	A row contains a different number of fields than the header. Correct the file so every row uses the same delimiter and field count.
FTP/SFTP read error	Check the server URL, credentials, path, network connection, and server permissions. Review the URL and transfer code included in the error.
FTP/SFTP upload error	Check the server connection, credentials, directory permissions, and available storage. The Connector retains the completed file locally when the remote upload fails.
A timed file is not completed at the expected minute	The time condition is checked only when another value arrives. Send or wait for the next sample after the configured time has elapsed.
A file is parsed as generic text instead of CSV	Confirm that the first line contains commas or semicolons. Only these delimiters are detected.
A local file is unexpectedly replaced	Another completed file used the same directory and filename. Add a timestamp or another unique value to Filename.

If the cause is not clear, review the Connector and system logs. See Configure and review system logs.

connector file ftp sftp csv xml troubleshooting

Contact Us