PI Connector For UFL 1.3.2 User Guide

PI Connector for UFL 1.3.
User Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (1) 510-297-5800
Fax: (1) 510-357-8136
Web: https://www.osisoft.com
PI Connector for UFL 1.3.2 User Guide

© 2016 - 2021 by OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission
of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, OSIsoft EDS, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API,
PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive,
PI DataLink, PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise,
PI OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square,
PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services,
RLINK, and RtReports are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein
are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC
license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12-212, FAR
52.227-19, or their successors, as applicable. OSIsoft, LLC.
Version: 1.3.2.139
Published: 9 February 2021
Contents
Introduction to PI Connector for UFL........................................................................... 1

PI AF structure for PI Connector for UFL data.................................................................................................. 3
PI Connector for UFL point data values........................................................................................................ 3
Pre-installation tasks for connectors........................................................................... 5

Software requirements for connectors............................................................................................................ 5
Connector security.......................................................................................................................................... 5
Security best practices for PI Connector for UFL.......................................................................................... 6
Configure firewalls ......................................................................................................................................6
Create the Windows account for the connector........................................................................................... 7
Create the PI identity for the connector....................................................................................................... 7
Map the Windows account to the PI identity................................................................................................8
Enable PI Data Archive access for the PI identity......................................................................................... 8
Create and configure security for the PI AF database...................................................................................9
Enable PI AF database access for the Windows account...............................................................................9
Identify the administration port number........................................................................................................10
Identify administration group users............................................................................................................... 11
Install the connector................................................................................................. 13

Configure silent installation for connectors....................................................................................................14
Change connector installation settings.......................................................................................................... 15
Uninstall the connector................................................................................................................................. 16
Uninstall the connector in silent mode....................................................................................................... 17
Configure the connector........................................................................................... 19

Open the PI Connector Administration site....................................................................................................19
Configure the server list.................................................................................................................................20
Modify the server list................................................................................................................................. 21
Configure purge time/output path/REST channel authentication...................................................................21
Add data sources to the connector................................................................................................................ 22
Data source description............................................................................................................................. 22
Configuration File...................................................................................................................................... 23
Data Source Type and Address...................................................................................................................23
User Name (REST)..................................................................................................................................... 25
Password (REST)....................................................................................................................................... 25
Scan Time..................................................................................................................................................25
New Line................................................................................................................................................... 26
Word Wrap................................................................................................................................................ 26
Store Mode............................................................................................................................................... 26
Locale........................................................................................................................................................26
Incoming TimeStamps............................................................................................................................... 27
Encoding....................................................................................................................................................27
REST Server mode responses.....................................................................................................................27
Modify the configuration file..................................................................................................................... 28
Modify data sources...................................................................................................................................... 28
Substitute characters in object names........................................................................................................... 29
Compression configuration............................................................................................................................30
Modifications to the connector PI AF structure.............................................................................................. 30
PI Connector for UFL 1.3.2 User Guide iii

Contents
Supported modifications........................................................................................................................... 30
Modify the point prefix.................................................................................................................................. 31
Start data collection...................................................................................................................................... 32
Configure PI Connector for UFL to process data............................................................................................ 32
Configuration file definitions...................................................................................................................... 33
Functions and operators............................................................................................................................ 39
Data storage in PI Points, AF elements and Event Frames..........................................................................44
Code flow control (IF statement)............................................................................................................... 48
FOREACH() statement.............................................................................................................................. 48
Iterating through comma-separated values............................................................................................... 49
Iterating through JSON arrays and receiving a value from a JSON element............................................... 50
Configuration examples.................................................................................................................................50
Data manipulation logic examples............................................................................................................. 51
Action examples........................................................................................................................................ 52
Migration from the UFL Interface.................................................................................................................. 57
General considerations.............................................................................................................................. 57
Removing unrecognized sections in the INI file.......................................................................................... 58
Changes to command line parameters...................................................................................................... 60
Connector administration......................................................................................... 63
Verify data collection..................................................................................................................................... 63
Verify connection from data source to connector.......................................................................................... 63
Diagnostics....................................................................................................................................................63
PI Data Servers.......................................................................................................................................... 64
PI Asset Servers......................................................................................................................................... 64
Message log.............................................................................................................................................. 64
Advanced Diagnostics............................................................................................................................... 65
Data buffering......................................................................................................... 67
Connector-to-PI System buffering................................................................................................................. 67
Troubleshoot buffering.................................................................................................................................. 67
Technical support and other resources....................................................................... 71
iv PI Connector for UFL 1.3.2 User Guide

Introduction to PI Connector for UFL
PI Connector for UFL is used to transfer contextual and time-series data from textual data
sources, such as ASCII and Unicode (UTF-8), to the PI System.
PI AF elements and event frames, along with PI points, are created automatically when the
connector receives data that pass the filters specified in the configuration INI file.
Operational overview
Once configured, the connector performs the following tasks:
1. The connector either periodically scans for new data in the configured folder, or enables the
communication on a REST channel. The communication on the REST channel can be
configured in two modes:
◦ listening - REST(server) mode

◦ actively executing an http/https GET command on given endpoints - REST(client) mode
Listening on a REST(server) endpoint means the connector expects data to be sent to an
address the connector opens. Data must be sent through https PUT or POST requests.
Actively executing the http/https GET command allows for reading from existing REST
endpoints by scanning them on a periodic basis.
For more information on this topic, see Add data sources to the connector.
2. If new data is available, the connector reads it, filters, and extracts the input from lines
based on the logic that is defined in the configuration INI file.
3. After the input is filtered and assigned to variables (declared in the INI file), events are
forwarded to PI points, PI AF elements, their attributes, and event frames. If any of these PI
entities are found not to exist, the connector creates and then updates them.
AF elements and event frames will always be accompanied by a template.
Note:
The connector cannot reference existing PI AF elements that it has not created.
PI Connector for UFL 1.3.2 User Guide 1

PI Connector for UFL Architecture Diagram
Data flow example (through the REST(client) channel)
2 PI Connector for UFL 1.3.2 User Guide

PI AF structure for PI Connector for UFL data

The PI AF structures created by the PI Connector for UFL depend upon the logic defined in the
configuration INI file. See Configuration examples for samples of AF structures that the
connector can create.
Examples can also be found on GitHub - PI Connector for UFL Samples (https://github.com/
osisoft/PI-Connector-for-UFL-Samples). They demonstrate how the INI file logic can be applied
to several types of CSV, JSON, and XML files. The resulted PI AF structures show how PI AF
elements and event frames simplify the navigation to PI tags.
PI Connector for UFL point data values

PI Connector for UFL creates PI points based on the logic specified in its configuration file. The
data type that is assigned to a newly created point reflects the data type that is used by the
variable that was referenced in the StoreEvent/StoreInPI function as the Value parameter.
The following table lists the mapping. For more information on this topic, see Data storage in PI
Points, AF elements and Event Frames.
Data type of the Value variable in StoreEvent() PI point data type
String String
Number Float64
Int32 Int32
DateTime Timestamp


Pre-installation tasks for connectors
Before installing the software, complete the following tasks. See subsequent topics for more
details about each task.
Procedure
1. Verify the host meets the software requirements for the connector.
For more information, see Software requirements for connectors.
2. If your connector is relay-enabled, install and start the relay before installing and starting
the connector.
3. If the data source has additional requirements for installation, complete those tasks.
4. Configure security for the connector and your network.
For more information, see Connector security.
5. Identify the administration port number.
6. Identify administration group users.
Software requirements for connectors

On the host where the connector is installed, the following versions of related software are
required:
• Operating system: See the connector Release Notes for compatible operating systems on the
OSIsoft Customer Portal (https://my.osisoft.com/).
• Web browser
◦ HTML5-compliant web browser for access to the PI Connector Administration site. The
following browser is supported (in desktop mode only):
▪ Google Chrome version 80 or later
Connectors also require the following versions of related software, which can be installed on
other hosts:
• PI System
◦ PI Data Archive 2018 SP3 Patch 1 or later
◦ PI AF Server 2018 SP3 Patch 2 or later
• For relay-enabled connectors, use PI Connector Relay version 1.x. Do not use PI Connector
Relay version 2 or later.
Connector security
Connector access to PI Data Archive and PI Asset Framework (PI AF) servers is based on
Windows Integrated Security.

Note:
Configure security settings before starting the connector.
Configure security settings for connectors to provide the connector secure access to your PI
System. Security must be configured to allow the connector to write to both the PI Data Archive
and PI AF servers. For more information about configuring security, refer to the following:
• For PI Data Archive, see the topics under "PI Data Archive security" in Live Library (https://
livelibrary.osisoft.com)
• For PI AF, see the topics under "PI AF server installation and upgrade" in Live Library
(https://livelibrary.osisoft.com)
Some data source protocols are inherently insecure. OSIsoft recommends that you review the
security standards for your data source to determine the appropriate security measures
necessary to secure your system.
Security best practices for PI Connector for UFL

Adhere to the following security guidelines for the individual channels. For an overview of the
channels, see Introduction to PI Connector for UFL.
• File channel
OSIsoft recommends setting correct permissions for the Windows directory files that the
connector reads. Only data consumers and data producers should have write access to the
configured files.
• REST Client channel

By default, PI Connector for UFL verifies the validity of a certificate provided by the server
to which the connector communicates. The option for verifying the certificate validity is
configurable. For further information, see Configure purge time/output path/REST channel
authentication. OSIsoft recommends not disabling the option for verifying the certificate
validity, but rather adding the untrusted server's certificate to a trustStore on the connector
machine. Microsoft Management Console (MMC) provides the Certificates snap-in for MMC.
See the Microsoft TechNet article Using the Certificates MMC Snap-in (https://
technet.microsoft.com/en-us/library/dd632619.aspx).
• REST Server channel

By default, the REST Server channel uses https transport. OSIsoft recommends using basic
authentication and a strong password to protect it. In order to prevent from denial-of-
service attacks (DoS attacks), OSIsoft recommends using the connector on an isolated
network or behind a firewall.
Configure firewalls
Typically, the connector and PI Servers are not installed on the same host. Since the connector
communicates with the PI Servers using TCP sockets, any network firewalls between the
connector host and the PI Server hosts must be configured to permit the following connections.
If there are multiple firewalls (including Windows firewall on the connector or PI Server
hosts), all firewalls in the connection path must be appropriately configured.

• Connection from connector to PI Data Archive
The default port for PI Data Archive clients is 5450. All firewalls between the connector and
PI Data Archive must allow the connector to open a connection to the administration client
port. For example, if Windows firewall is enabled on the PI Data Archive host, Windows
firewall needs to allow incoming connections to the client port from any connector host that
needs to add the PI Data Archive server to the connector service list.
• Connection from connector to PI AF

The default port for PI AF clients is 5457. All firewalls between the connector and PI AF
must allow the connector to open a connection to the client port. For example, if Windows
firewall is enabled on the PI AF host, Windows firewall needs to allow incoming connections
to the client port from any connector host that needs to add the PI AF to the connector
service list.
Create the Windows account for the connector

You must create a Windows account to host the connector. There are two types of accounts:
• Windows domain accounts are the more secure option for hosting the connector. In a
domain environment, a domain controller performs authentication for centralized control.
• Windows workgroups are the less secure option for hosting the connector. In a workgroup
environment, all computers are peers and authentication is performed locally.
Note:
For best security, run the connector on a host that is a member of a Windows domain and
use a domain account for its identity.
Procedure
1. Determine whether the connector host is part of a Windows domain or workgroup.
Computer domain information can be found in the Control Panel system information, in the
Computer name, domain, and workgroup settings area.
2. Create either a dedicated domain account, or local accounts for the connector.
Note:
The account should not be a member of the host's local administrators group.
◦ If your computer is part of a domain, create a dedicated domain account for the
connector.
You must have domain administrator privileges to create domain accounts.
◦ If your computer is part of a workgroup, create identical local accounts on every machine
that hosts either the connector, the PI Data Archive server, or PI AF server, using the same
user name and password for each account.
You must have local administrator privileges to create local accounts.
Create the PI identity for the connector

Create the PI identity to give the connector permission to write data to the PI Data Archive.

Procedure
1. Launch PI System Management Tools (PI SMT).
2. Click Security > Identities, Users, & Groups, and then click the PI Identities tab.
3. Right-click within the pane, and then click New Identity.
The New Identity window opens.
4. Configure the settings for the identity.
The PI identity for the connector must have permission to write to the PI Data Archive.
5. Click Create.
Map the Windows account to the PI identity

Map the Windows account to associate the PI identity for automatic authentication on the PI
Data Archive server.
Procedure
1. Launch PI System Management Tools.
2. Click Security > Identities, Users, & Groups, and then click the PI Identities tab.
3. Double-click the PI identity for the connector.
4. On the Mappings & Trusts tab, click Add under the Mapping and then add the account to be
used by the connector to the Windows Account field.
5. Click Create.
6. On the identity Properties dialog box, click OK.
Enable PI Data Archive access for the PI identity

Provide the new PI identity for the connector with the required access to the PI Data Archive
using PI System Management Tools.
Before you start

You must have already created a PI identity for the connector.
Procedure
1. Launch PI System Management Tools, and then click Security > Database Security.
2. Right-click the PIPOINT table and then click Properties.
The Security window opens.
3. Click Add to open the Select window, and then select the identity to add to the access
control list.
4. Enable read and write access to the PIPOINT table, and then click OK to save the settings
and close the window.

Note:
For connectors that create digital points, read-write access to the PIDS table is also
needed.
Create and configure security for the PI AF database

If you are installing the connector on a PI System that uses PI AF, you must perform the
following steps to create and configure the PI AF database.
Failure to create and configure the PI AF database results in an error message when you start
the connector that reads: Cannot complete the operation because the user does
not have rights to write to Element 'X' with Unique ID 'Y'.
Manually create the PI AF database and provide the Windows account for the connector with
the required access to PI AF using PI System Explorer. Optionally, the connector can
automatically create the database depending on the proper permissions.
Note:
You must be logged into a Windows account that has PI AF administration privileges to
perform the following procedure.
Procedure
1. To manually create the PI AF database, open PI System Explorer and click the Database
button.
The Select Database window opens.
2. Click the New Database button.
3. Enter the name for the database and click OK.
Note:
The new database name must match the name used in the server configuration for the
connector.
PI System Explorer creates the new PI AF database.
Enable PI AF database access for the Windows account

Provide the Windows account for the connector with the required access to the PI Asset
Framework (PI AF) database using PI System Explorer.
Before you start

You must have already created a Windows account for the connector.
Procedure
1. Launch PI System Explorer, and then click the Database button.
The Select Database window opens.
2. Click the security icon .
The Permission for Databases window opens.

3. Click Add, and then select the Windows account for the connector.
4. Select Read/Write and Read/Write Data, and then click OK.

5. Enable access to the database for the Windows account for the connector. Select and
configure each of the following in the Items to Configure list:
◦ Elements
◦ Element templates
◦ Enumeration sets
◦ Optional: Event Frames. This is required only when the connector generates Event
Frames.
◦ Select the Windows account for the connector, then select Allow for Read/Write and
Read/Write Data.
6. Click OK to save the settings and close the window.
Identify the administration port number

The connector service uses a TCP port to host the administration web service. If you intend to
access the web service from a remote host, all firewalls between the remote host and connector
host must permit a browser on the remote host to open a connection to the web service. For
example, if Windows firewall is enabled on the connector host, configure Windows firewall to
allow access to the configured web service port from approved remote hosts.
Determine an unused TCP port for the web service before installing the connector software.
You are prompted to enter this port number during installation.
Procedure
1. Open a command prompt and enter: netstat -a -n -p TCP | find "LISTENING"
The tool displays only TCP ports that are currently in use.
2. View the last set of numbers in the second column to determine ports that are in use.
For example, the preceding figure shows that ports 80, 135, 445, and so on are in use. The
default port 5460 is available, or you can choose another unused port. Since default and

other well-known ports can be the targets of cyber attacks, choosing a non-default port can
provide an additional defense.
Identify administration group users

To configure and administer the connector, users must belong to the local Windows PI
Connector Administrators group. You will be prompted to add these users during installation.
After installation, you can use Windows Administration tools to add or remove users from the
PI Connector Administrators group at any time.
Note:
Use care when selecting users for the PI Connector Administrators group. Users will be
able to locally or remotely stop and start the connector, and modify configurations.
Procedure
1. Identify all local or domain users that require connector administrative privileges.
2. Open the Run window and enter: lusrmgr.msc, then click OK. The Local Users and Groups
window opens.
3. Double-click Groups.
4. Double-click PI Connector Administrators.
5. Click Add.
6. Enter the user's name, then click Check Names and select the user from the list and click
OK.
7. Click OK.


Install the connector
If any prerequisite software included in the connector setup kit has not been installed, the
setup program prompts you to configure the additional software included in the setup kit
before installing and configuring the connector software.
Before you start
• Complete pre-installation tasks for connectors.

• Ensure all connector-specific installation requirements are met.
• Log on to a Windows account with administrator privileges.
Procedure
1. Double-click the connectorname.exe file. The self-extracting executable window opens.
2. Set the extraction path for the installation files and click OK. The setup program opens
displaying the installation files.
3. Click OK. The connector setup wizard opens.
4. Click Next. The Port Configuration window opens.
5. Enter an administration port number for hosting the administration web service.
6. Click Check Availability. If the port is available, the message Port is available, click
Next to continue is displayed.
7. Click Next. The Windows Service Configuration window opens.
8. Enter a domain and name and password for the account that will run the connector service.
9. Click Validate. If the account and password are correct, the message Valid name and
password combination is displayed.
10. Click Next. The Alternate Buffer File Location windows opens.
11. Optional: Click Browse to select alternate file paths for buffering and other files. If you do
not specify a path, the files default to:
%ProgramData%\OSIsoft\Tau\connectorName.ConnectorHost\connectorName
Connector
12. Click Next. The Ready to install PI Connector window opens.
13. Click Install. The Installing PI Connector window opens and displays a progress bar that
indicates the status of the PI Connector installation.
14. Click Next. The Configuration Security window opens.
15. As necessary, add users to the PI Connector Administrators group:
◦ Click Add User to add the current user to the PI Connector Administrators local
group.
◦ Click Launch to add any other local or domain users that require connector
administrative privileges to the PI Connector Administrators group.

1. Adds the current user to the group.

2. Opens a window to add specific users or groups.
16. Click Next. The Install Completed window opens.
17. Click Finish. The Installation Complete window opens.
18. Click Close.
After you finish

Note:
Catalog files are separate downloadable files, and are used for application whitelisting. If
you use whitelisting, install the catalog files associated with your OSIsoft products to
ensure that those products function as intended. Windows catalog files that have been
digitally signed by OSIsoft can be used as a digital signature for 3rd party and other
unsigned components installed by OSIsoft setup kits. This facilitates a trusted way to
verify these components and may be used for whitelisting purposes. For information on
how to use catalog files for whitelisting, refer to the OSIsoft Knowledge Base article:
Whitelisting PI applications based on catalog files (https://customers.osisoft.com/s/
knowledgearticle?knowledgeArticleUrl=KB01975).
Configure silent installation for connectors

You can install this software with the Windows silent installation feature. Sometimes called an
unattended installation, silent installation requires no user interaction during the setup
process. System administrators with an automated software distribution application might use
silent installation to deploy software automatically to large numbers of corporate computers.
Modify the silent.ini file to configure silent installation. Configuring the silent.ini file
determines items that you would have selected during a normal installation with the connector
installation wizard.

Before you start

Pre-installation tasks for connectors.
Procedure
1. Prepare the silent installation file path and identify the status of supporting software.
a. Run the connector setup kit self-extracting executable file.
The self-extracting dialog box opens. You will only complete the step to extract the
installation files, not actually proceed to install the connector or prerequisites.
b. Enter an extraction path and click OK. The installation files are extracted and the setup
program opens.
c. Cancel the installation.
2. Go to the extraction folder, and open the silent.ini file in a text editor.
3. Modify the COMMANDLINE section for the module for the connector.
See the silent.ini file included in the setup kit for more details about each of the
configurable settings:
◦ Required: SERVICE_ACCOUNT. Set this property to the name of the Windows account for
the connector service.
◦ Required: SERVICE_ACCOUNT_PASSWORD. Set this property to the password for the
Windows account for the connector service.
Note:
The password in the silent.ini file is visible to any user who has read access to
the file. Protect all copies of the file with an access control list that allows read
access to only a white list of users who know the password and denies read access
to all other users. Preferably, remove the file immediately after installation. If long-
term retention is necessary, keep the file on removable media that is stored offline
in a physically secure location.
◦ Optional: USERPORT
◦ Optional: ALTERNATEFILEPATH
4. To run the silent installation, open a command prompt window, change the working
directory to the extraction path, and enter setup.exe -f silent.ini.
Change connector installation settings

Warning:
Before changing installation settings, backup or save configuration so that those settings
can be referenced later if necessary.
The following installation settings can be changed from the connector installation wizard
accessed from the Windows Control Panel. Change installation settings for your connector
when:

• Reinstalling the connector software

• Replacing missing files from the installation
• Changing the administration port number
• Changing the location of the buffer and data files
• Changing the Windows account for the connector service
Note:
To remove users from the PI Connector Administrators Group, modify the Windows User
Accounts configuration through the Windows Control Panel.
Procedure
1. Open Programs and Features as an administrator from the Windows Control Panel.
2. Select the connector program, and then click Change.
Note:
Changing installation settings stops the connector service.
The connector installation wizard opens.
3. Click Next.
The installation and change options are shown.
4. Click Change to modify the settings.
5. Change installation configurations using the wizard.
Uninstall the connector

To uninstall a connector, you must use an account with administrator privileges.
Warning:
Before uninstalling the connector, backup or save configuration so that those settings can
be referenced if reinstalling later. Uninstalling the connector will remove all configuration
files in the directory.
Procedure
1. From the Windows Control Panel, click System and Security > Administrative Tools >
Services.
2. In the Services (Local) window, scroll to the service for your PI Connector.
3. Right-click the service and then click Stop.
4. Uninstall the connector using one of the following methods:
◦ From the Windows Control Panel, open Programs and Features, then select the
connector and click Uninstall.
◦ In the extraction folder created by the setup kit, right-click the ConnectorName.msi file
and then click Uninstall.

Note:
The version of the ConnectorName.msi file must be the same as the installed
connector.
Uninstall the connector in silent mode

Use silent mode to uninstall the connector from the command line.
The original ConnectorName.msi file or a copy of the same version must be used for silent
uninstall.
Procedure
1. Open a command prompt window.
2. Change the working directory to the folder containing the ConnectorName.msi file.
3. Enter msiexec -x ConnectorName.msi -qn.


Configure the connector
To begin collecting data, add and configure the servers and data sources for the connector.
Topics in this section

• Open the PI Connector Administration site
• Configure the server list
• Configure purge time/output path/REST channel authentication
• Add data sources to the connector
• Modify data sources
• Substitute characters in object names
• Compression configuration
• Modifications to the connector PI AF structure
• Modify the point prefix
• Start data collection
• Configure PI Connector for UFL to process data
• Configuration examples
• Migration from the UFL Interface
Open the PI Connector Administration site

Configure and perform administration tasks for the connector from the PI Connector
Administration site using an HTML5-compatible browser.
Before you start

To configure the connector, the following must be true:
• Your user account must belong to the local Windows PI Connector Administrators
security group.
• The connector service must be running. From the Windows menu, run services.msc to
open the Services window, and then locate and start the connector service.
If you want to access the PI Connector Administration site from remote computers, configure
firewalls to permit remote access to the service port. For more information on configuring
firewalls, see Configure firewalls.
Procedure
• When using the computer where the connector is installed, from the Windows Start menu,
select All Programs > PI System > PI Connector for connector_name Administration .

Note:
◦ When using a remote computer, enter the following URL in the browser's address
bar: https://connectorNodeName:port#/admin/ui
◦ Some web browsers do not recognize the security certificate from the
administration site. If alerted of a security certificate, click Yes to continue.
The PI Connector Administration site opens to the main Overview page.
Configure the server list

Add and configure PI Data Archive and PI AF for communication with the connector.
You can add and remove servers without stopping the connector data collection.
Note:
The connection status of a server stays Disconnected until the connector begins
collecting data.
Procedure
1. On the PI Connector Administration page, click the Server List link.
The Server List pane displays the PI Data Archive and PI AF servers for the connector.
2. Add and configure one or more PI Data Archive servers to the PI Data servers list, and then
click Add.
Note:
For a PI Data Archive collective, add each member of the collective to the PI Data
servers list, not the collective itself.
◦ PI Data servers
A descriptive name or alias for the PI Data Archive server.
◦ Hostname or IP address
The host name or IP address of the PI Data Archive server.
3. Add and configure one or more PI AF servers to the PI Asset servers list, and then click Add.
◦ PI Asset servers
A descriptive name or alias for the PI AF server.
◦ Hostname or IP address
The host name or IP address of the PI AF server.
4. Enter additional information for the PI AF server, and then click Keep these settings.
◦ PI Asset Database
The name of the PI AF database.
◦ Root PI Asset Path

The path to the PI AF element named "connector name Connector", under which the
connector creates an asset hierarchy. The path can be empty. A non-empty path must

conform to the PI AF syntax for element paths with the restriction that the path cannot
begin or end with a backslash path separator character.
◦ PI Data server
The host name or IP address for the associated PI Data Archive.
Modify the server list

Modify the server list for the connector from the PI Connector Administration site.
You can add and remove servers without stopping the connector data collection.
Procedure
1. In the navigation pane, click Server List, or click the Add or modify servers link in the
Servers configured to receive data from the connector area.
2. To modify the server list, choose one of the following options:
◦ Add a new server.
◦ Remove an existing server.
3. To modify an existing server, delete the server, and then add it with the new configuration
parameters.
Configure purge time/output path/REST channel authentication

Purge time
By default, PI Connector for UFL deletes (purges) the zipped processed files that are older than
10 days.
Output path
By default, PI Connector for UFL stores the processed data files in %PROGRAMDATA%\OSIsoft
\PI Connectors\UFL.ConnectorHost\Output folder.
REST channel authentication

By default, PI Connector for UFL has its REST Server endpoint with Basic authentication
enabled.
REST certificate validation

By default, PI Connector for UFL validates the REST certificate by verifying that it is available
on the REST Server so that the connector can then communicate through the REST Client
channel.
You can change the above settings by running the GlobalConfig.ps1 PowerShell script
located in %PIHOME64%\Connectors\UFL\PowerShellScripts folder.
Note:
Run the GlobalConfig.ps1 script in PowerShell and it will indicate the syntax needed
for viewing and/or changing of the existing settings.

Add data sources to the connector

Add data sources for data collection from the PI Connector Administration Site page.
Procedure
1. From the Overview window, either click the Add or modify data sources link found under
Data Sources in the right pane, or click the Data Source List link in the left pane. Either link
opens the Data Source List window.
2. To add a new data source, enter the name in the Data source name field, and then click Add
and configure.
Note:
All Data source name values for the connector must be unique.
Configurations are not case-sensitive. For example, DataSource1 and DATASOURCE1
are considered the same.
The configuration window opens.

3. Enter and select your data source configurations listed, and then click Save.
◦ Data source description
◦ Configuration File
◦ Modify the configuration file
◦ Data Source Type and Address
◦ User Name (REST)
◦ Password (REST)
◦ Scan Time
◦ New Line
◦ Word Wrap
◦ Store Mode
◦ Locale
◦ Incoming TimeStamps
◦ Encoding
◦ REST Server mode responses
The Overview page opens and lists the new data source.
Data source description

Optional: If you add more than one data source, use this description field to identify the unique
characteristics of each.

Configuration File
Required: Specify the full path to the configuration INI file.
Note:
Be aware that pointing to the configuration INI file in the connector configuration copies
the file to the internal repository of the connector; therefore, to apply changes to an INI
file that has already been read by the connector, you should follow the steps detailed in
Modify the configuration file.
Data Source Type and Address

Required: Specify the data source type and the address from which the incoming data will be
taken.
There are four data source types: File, REST Server Basic, REST Server API Key, and
REST Client.
• File
The File option specifies the path and mask from where the input files will be copied. For
example:
D:\UFL\Input\Data\*.dat
or,
\\DataShare\Input\Data\*.csv
Unzip input files: The connector is capable of opening and processing the content of ZIP
archives. If you want to process both the not-zipped files as well as the ZIP archives, specify
the keyword zip at the end of the path and mask. Use the pipe | as the delimiter. For
example: D:\UFL\Input\Data\*.dat | zip.
Note:
The mask is applied on files found in the root of the ZIP archive. The content of any
subdirectory is ignored.
After processing is complete, the ZIP archive is moved to the output folder.
• REST Server Basic

With this selection, the Address field should remain empty as it will be populated
automatically with the REST endpoint address at which the connector listens. The endpoint
address will display after the data source configuration settings are saved and reopened.
The endpoint address pattern is:
For PUT requests:
https://ComputerName:port#/ConnectorData/DatasourceName/
For POST requests:
https://ComputerName:port#/ConnectorData/DatasourceName/Post

In this mode, the connector expects the data to be pushed to the above address. The data
format is arbitrary, and every PUT or POST request executed by a client brings in a textual
input onto which the INI logic is applied.
By default, the REST endpoint is configured to use Basic authentication and requires that a
user name and password combination be provided in a request. The password cannot be
blank; no other rules are enforced.
The PowerShell script example DataPutExample.ps1 located in the %PIHOME64%
\Connectors\UFL\PowerShellScripts folder shows how the client side logic should
appear.
• REST Server API Key

The other option for a secure REST communication is to use the API key method, also
known as the Token method name. If selected, the connector verifies that all incoming HTTP
requests have the correct key-value pair in their headers. The key must match with what is
entered in the User Name input and the value is verified against the Password entry. The
Address field will again be auto-populated.
The REST Server channel replies to client requests with response codes. See REST Server
mode responses for details.
• REST Client
The REST Client channel expects the endpoint address on which the GET command will be
executed. For example:
https://restcountries.eu/rest/v1/alpha/LIE
Executing the GET command on the above REST endpoint brings back the structured text
(JSON format) about one European country.
Note:
The returning data format can be JSON, XML, CSV or a plain text.
REST endpoint parameters
There are three options for extending the REST Client URL address with parameters:
◦ List of static parameters

In scenarios where the REST endpoint URL allows for a parameter, the connector logic
offers the option to list the individual parameter values and suffix them to the endpoint
address. The keyword UFL_Placeholder is used to indicate that the following part of
the URL lists the individual parameters divided by the pipe '|'character. With this syntax,
more GET commands can run simultaneously. For example, to execute three GETs on the
URL:
https://restcountries.eu/rest/v1/alpha/parametervalue
You can write the following into the Address edit box:
https://restcountries.eu/rest/v1/alpha/UFL_Placeholder|LIE|DE|AT
As a result, the connector logic will execute three GET commands, each using one of the
pipe-delimited parameter values.
With the previously described logic, you can replace any part of the endpoint address
denoted by the UFL_Placeholder keyword, not only the parameter part. For example:

UFL_Placeholder:6894/RESTServiceImpl.svc/json/|10.105.0.1|
10.105.0.2|10.105.0.3
◦ Dynamic parameters
If the URL needs to be parameterized by time, you can suffix it by the following pattern:
{relative time, output format}
Relative time format complies with the PI Time format rules, where asterisk *
denotes current time. The output format complies with the Date and Time format
specifiers described in Custom Date and Time Format Strings (https://
docs.microsoft.com/en-us/DOTNET/STANDARD/BASE-TYPES/custom-date-and-time-
format-strings). For example:
http://servername.com/data?
start={*-10m,yyyyMMdd_HHmm}&end={*,yyyyMMdd_HHmm}
The result is the text executed through the http GET command:
http://servername.com/data?start=20190228_0950&end=20190228_1000
◦ HTTP headers
Some HTTP servers require the client to send a set of operating parameters for the HTTP
transactions. These parameters are called HTTP headers and the connector allows their
definition in the form of a colon-separated name-value pair. You define the parameters
manually in: %PIHOME64%\Connectors\UFL\Configuration
\Datasource.config.json.
The HttpHeaders keyword is predefined for each data source, and initially it defines an
empty string. For example, to specify two HTTP headers, replace the empty string with
corresponding name-value pairs in square brackets and separate them by coma:
"HttpHeaders":
"[User-Agent:OSISoft UFL Connector/1.2.1.x],
[Accept:application/vnd.noaa.dwml+json;version=1]"
Note:
The connector has to be restarted in order to activate the HttpHeaders setting.
User Name (REST)

Required for the REST channels: When the data source type is REST, this entry defines the user
name which will be used for authentication.
Password (REST)
Required for the REST channels: The parameter defines password for the user name specified
above and it is used for REST authentication.
Scan Time
Required: The parameter defines the time period between scans in seconds.

If needed, an offset can be specified. Offset is counted from the midnight of the current day. The
offset format is: hh:mm:ss and must be put after the number of seconds representing the scan
interval. Use comma as the delimiter.
For example, a daily scan triggered 5 minutes after midnight:
86400,00:05:00
New Line
Required: Specify the line-end character(s). If left empty, CRLF is assumed (ASCII 13 and 10). If
the lines in the input stream are terminated in more than one way, specify the line endings in
double quotes and use the OR clause to set the valid line endings, for example:
"event end>" OR "STOP"
When you have to use ASCII codes for line endings, use comma-separated numbers with no
white space in between, for example:
13,10
You can also combine the line endings expressed as ASCII codes with string representation, for
example:
"event end>" OR 13,10
String comparisons are case sensitive.
Word Wrap
Optional: A positive whole number that defines the length of the chunks (lines) the input text
will be broken into. All lines forwarded to the parsing engine of the connector will be of the
same length.
If -1 is used, the connector will take the whole input stream and forward it as one line for
parsing.
Note:
The -1 setting is mostly intended for structured formats like JSON because if the JSON
parser is applied to an incomplete JSON structure, it will return an error.
When set, the Word Wrap overwrites the New Line definition.
Store Mode
Required: Specifies whether the connector will insert or update values in PI points. When a PI
point has a value at a given timestamp, the Update selection causes the new incoming values to
overwrite it. The Insert selection causes a value to be added for that timestamp.
Locale
Required: Defines how the connector transforms the string representation of numbers to the
native numeric form; that is, which locale it uses.

Incoming TimeStamps
Required: Specifies whether incoming time stamps are UTC or Local time.
Encoding
There are two encoding options:
• Extended ASCII (8-bit encoding, default)

In the Extended ASCII mode, all input streams are read as characters coded on one byte with
8-bit encoding. Characters with codes higher than 127 are interpreted as a Windows 1252
code page.
Note:
If a Unicode input is processed in the Extended ASCII mode, the connector replaces the
characters coded on two or more bytes with question marks '?'.
• Unicode (UTF-8 encoding)

With version 1.3, the connector has been enhanced to deal with the Unicode-based input
encoded in UTF-8. In this mode, PI AF based objects, such as elements, event frames, and
their attributes, can be created and updated so that they accommodate international
characters
Note:
In Unicode mode, input streams which contain plain English text, that is, ASCII
characters coded on the interval <1,127>, do not make a difference because UTF-8
encoding is backward compatible with ASCII.
The INI logic itself cannot contain any Unicode characters.
When the connector is set up to operate in Unicode mode, there are several limitations
because neither the INI logic nor PI point names can contain characters encoded on more
than one byte. PI points and their attributes can only accommodate ASCII characters. Hence,
the StoreEvent() function, when provided with a tag name containing Unicode characters,
forwards a modified tag name to PI Data Archive. The connector's modification logic
replaces Unicode characters with the string representation of the individual hexadecimal
codes prefixed by U+. For example: Strings encoded in UTF-8 that are forwarded to PI Data
Archive through the StoreEvent() function will have the following PI tag name(s):
UTF-8 based input PI tag name
Größe1 GrU+00F6U+00DFe1
газ в зоне 1 U+0433U+0430U+0437 U+0432 U+0437U
+043EU+043DU+0435 1
REST Server mode responses

The connector's REST endpoint always replies to client's PUT/POST commands with a status
and a short description of the operation result. The table below lists the most common
statuses:

Message Status Corrective Action

Done 200 OK
Forbidden 403 Forbidden Verify the URL address, username and/or
password.
Data queue is full 500 Internal The REST endpoint is overloaded; re-send
server error the data.
Method not allowed 405 Method not Verify the URL address.
allowed
The remote name could not
be resolved
The operation has timed
out
Unable to connect to the
remote server
Note:
If the endpoint responded with status 500 (and the message Data queue is full), it
means that the data has not been accepted by the connector. The recommended approach
is to repeat the PUT/POST operation after a short while until the status 200 appears. An
example of such logic can be found on GitHub - PI Connector for UFL Samples (https://
github.com/osisoft/PI-Connector-for-UFL-Samples/tree/master/REST_DATA_SENDERS
%20%28REST%20SERVER%29). To log all the REST acknowledgement messages and
statuses, activate the verbose or information logging level on the administration page
of the connector.
Modify the configuration file

When adding data sources to the PI connector and modifying the configuration file to point to
an INI file, the INI file settings are copied into the connector repository. If you modify the INI
file, you must read the file into the connector repository for the changes to take effect. Follow
the steps in this topic to ensure that changes to the INI file are read by the connector.
Procedure
1. Open the INI file in a text editor.
2. Apply your changes and save the file.
3. Click either the Change or Delete button in the Data Source configuration page.
4. Navigate to the appropriate directory and select the INI file.
5. Click Save at the bottom of the configuration page.
If no syntax problems were encountered, the INI will be accepted. If problems are
encountered, an error message is displayed with the line number of the error. In that case,
edit the INI file again to correct the problem and repeat the previous steps.
Modify data sources

Modify data sources for the connector from the PI Connector Administration site.

Procedure
1. In the navigation pane, click the Data Source List link, or on the Overview page in the Data
sources for the PI Connector area, click Add or modify data sources.
2. Click the See Configuration link.
3. Edit the data source configurations and click Save.
Substitute characters in object names

PI Connector for UFL includes a function that allows for the substitution of characters that are
not supported in PI Point names, PI AF Element names, PI AF Element attribute names, Event
Frames, and Event Frame attribute names. While the best practice is to avoid using "illegal"
characters (including * ' ? ; { } [ ] | \ ` ") as part of object names, it is sometimes difficult to
guarantee that the data source will not produce such characters. If this is your case, use the
following procedure to replace the default substitution of the unsupported characters the
connector implements with new characters that you define.
Procedure
1. Stop the connector and the connector service.
2. Navigate to: %PIHOME64%\Connectors\UFL\Configuration and open the
ConnectorGlobal.config.json file.
3. Add Key-Value pairs to SubstitutionCharactersListsection. For example:
{"Key":"|","Value":""} or {"Key":"?","Value":"-"}
Note:
◦ A character can be replaced with nothing, "".
◦ If more than one character is in the key, you will get an error. If more than one
character is in the value, only the first character will be taken.
◦ Backslash (\) and double-quotes (") must be prefixed with the backslash escape
character.
The modified global configuration file should look like the following example:
{
"connectorglobal": {
"ConfigObject": {
"OutputPath":
"C:\\ProgramData\\OSIsoft\\PI Connectors\\UFL.ConnectorHost\\Output",
"PurgeTime": 1,
"RestBasicAuthentication": 1,
"ActiveRestVerifyCertificates": false,
"SubstitutionCharactersList": [
{
"Key": "\"",
"Value": ""
},
{
"Key": "\\",
"Value": "/"
},
{
"Key": "?",
"Value": "-"
}

]
}
}
}
4. Start the PI Connector for UFL service.
Results
Object names with substituted characters will be created once values are received.
Note:
Using the substitute function creates a new object name. It does not rename the object
that has already been created. For instance, if you attempt to rename a PI point using this
feature, a second point will be created leaving the so-far-collected events in the original
point.
Compression configuration
When the connector creates a PI point, the point's Compressing attribute is set to Off (or 0).
The other compression attributes (CompDev, CompDevPercent, CompMin, and CompMax) are
set to the server default values.
To specify compression attributes for individual points, use the Point Builder tool in PI System
Management Tools (PI SMT). For more information, see the PI Server topic "Point Builder" in
Live Library (https://livelibrary.osisoft.com).
To specify compression attributes for many points, edit the points in bulk using PI Builder. For
more information, see the PI Server topic "PI Builder" in Live Library (https://
livelibrary.osisoft.com).
For more information about compression attributes, see the PI Server topic "CompDev,
CompDevPercent, CompMax, and CompMin" in Live Library (https://livelibrary.osisoft.com).
Modifications to the connector PI AF structure

You can modify the PI AF structure that is generated by the connector. The topics that follow
describe modifications that you can make to the PI AF structure without interfering with the
functionality of the connector. Unsupported modifications are also shown.
Supported modifications
Add custom PI AF attributes
You can add custom attributes to the elements that were generated by the connector. To enable
the ability to add custom attributes, perform the following steps:
1. Open PI System Explorer and open the PI AF database associated with the connector.
2. In the Elements menu, find the element you wish to modify and determine the template
from which it is derived.

3. Open the Element Templates menu by selecting Library > Templates > Element Templates,
then locate the template from step 2 and select Allow Extensions on the General tab.
4. Return to the desired element in the Elements menu and add the custom attribute(s).
Note:
Any custom attributes that are added cannot be configuration items; that is,
Configuration Item must not be selected for the attributes.
Custom attribute templates can also be added to an element template, as long as Allow
Extensions is selected on the element template and Configuration Item is not selected for any
attribute templates that were added.
PI AF template modification
Several modifications to PI AF element templates that are generated by the connector are
allowed. You can add Extended Properties to the element template, assign a category to
attribute templates, and select Allow Extensions. You can also add PI AF Analysis rules directly
to an element or an element template.
PI point configuration modification

It is possible to modify selected point attributes after they are created by the connector.
• Modification of the compression settings attributes

• Modification of PI point security settings
• Attributes like Step, Scan, Archiving, Span, Zero, Typical, and Value
Note:
Any point attributes synchronized by the connector will be reset on connector restart.
Unsupported modifications
The following modifications to the PI AF structure that is generated by the connector are not
currently supported:
• Deleting element templates created by the connector

• Renaming element templates created by the connector
• Deleting template attributes created by the connector
• Renaming template attributes created by the connector
• Changing data type of attributes created by the connector
Modify the point prefix

To avoid collision with the data streams in the connector, the connector ID is prefixed to the
points for which it collects data. You can customize this point prefix by modifying the
configuration file.

Procedure
1. Navigate to %PIHOME64%\Connectors\ConnectorName\Configuration\ and open the
file PIPointPrefix.config.json. For each server that a connector sends data to, the file
includes an entry with the PI Data Archive server name and connector ID. For example:
"MyServer": {
"Name": "MyServer",
"PIPointPrefix": "Example Connector"
}
2. Change the PI point prefix. For example:
"MyServer": {
"Name": "MyServer",
"PIPointPrefix": "New Prefix"
}
3. Stop the connector.
4. If you previously ran the connector and collected data on existing points, rename those
points, changing the old prefix to the new prefix.
Caution:
If you skip this step, the connector leaves the PI points with the old prefix and creates
new PI points with the new prefix. Data is not copied from the old PI points to the new
renamed PI points.
5. Start the connector.
Start data collection

Begin data collection from the PI Connector Administration site after configuring the
connector.
Caution:
Do not start the connector until the first servers have been added to the connector
configuration.
Procedure
1. On the Overview page, find the Status of the connector area.
2. Click Start connector.
Configure PI Connector for UFL to process data

To specify how the connector processes incoming data, you create a configuration INI file.
The configuration file is composed of sections that define how the incoming data is split into
fields, then processed, and then written to PI tags, PI AF elements, or event frames.
Concrete examples can be found on GitHub - PI Connector for UFL Samples (https://
github.com/osisoft/PI-Connector-for-UFL-Samples/tree/master/INI_FILE_EXAMPLES). You
will find a set of INI files accompanied with sample data input there. The INI logic as well as the
scripts and data input can be downloaded and modified accordingly.

The following topics explain configuration files in detail. Refer to the referenced GitHub
address, or see the commented examples in Configuration examples for more input on the
individual functions and features.

• Configuration file definitions
• Functions and operators
• Data storage in PI Points, AF elements and Event Frames
• Code flow control (IF statement)
• FOREACH() statement
• Iterating through comma-separated values
• Iterating through JSON arrays and receiving a value from a JSON element
Configuration file definitions

Regardless of the source, incoming data is treated as a set of consistently formatted lines,
which are referred to as messages. Messages are further split into fields, which are then
assigned data types and, if required, formats that describe the layout of the field (for example,
for incoming DateTime fields).
Blank lines in the configuration file are ignored. To insert comments, precede text with a single
quote (ASCII 39). For example:
'-------------------------------------------------
' Get QUANTITY DETAILS
'-------------------------------------------------
To continue a line, end it with an underscore (ASCII 95). For example:

message1.filter = C1=="Line containing *" And _
C56=="DateTime*"
Note:
The maximum line length supported by PI Connector for UFL is 5120 characters.
• FIELD
Defines and declares data types for the individual fields that receive data.
• MSG
Defines the types of incoming messages, and assigns a name that is used to define the
section where the message is divided.
• Per message sections

For each message that is defined in the MSG section, the Per message sections filter
incoming messages, divide the messages into fields, process the fields, and then write the
results to PI tags, PI AF elements, or event frames. These sections can contain processing
logic, such as logic that redirects to other sections and skips lines from the input stream.

[FIELD] section statements

The statements in the [FIELD] section assign a name and data type to fields.
For date/time fields, you must specify the format used by incoming data. The [FIELD] section
is mandatory and must follow the [INTERFACE], [PLUG-IN] and [SETTING] sections.
To assign field attributes, use "dot" notation, as follows:
Field attributes
FIELD(n).Name = "Valid-Field-Name"
FIELD(n).Type = "Data-Type"
FIELD(n).Format = "DateTime Format"
Field names
• Field names are not case-sensitive, and must be composed of alphanumeric characters only
(no punctuation).
• Field names must not begin with a number.
• Do not use the C1, C2, …Cn keywords because they signify character position in a character
string.
• To ensure that your configuration file is readable, assign descriptive names to incoming
fields.
• For clarity, avoid assigning names that might be confused with the interface's reserved
words (such as "FIELD", "MSG", "TIME", and so on).
• Do not use any special characters. Special characters include punctuation marks, control
characters, typography elements like Em and En, mathematical operators and symbols,
slashes, dashes, brackets, braces, and underlines.
Data types
The PI UFL interface supports the following data types:
• DateTime (instant, precision - 0.0001s)
• Time (duration, precision - 0.0001s)
• String (default data type)
• Int32 (integer type)
• Number (double type)
• Collection (string, variant; set of name-values pairs)
Values in strings are cast to numbers according to the LOCALE setting. Scientific (exponential)
notation is recognized.
Data types conversions

The interface does not have an explicit CAST() function. Implicit conversion occurs when a field
or a variable of one type is assigned to a variable of a different type. If the conversion is not
valid, a run-time error is raised and the interface stops processing the affected line. The line
where the error occurred is consequently stored in the error file (MSGINERROR) and the
interface continues processing the next line in the file.

Date/time format
To specify the format of incoming date/time and time (duration) fields, define a format string
in the form:
Incoming date format string
InputTimeFieldName.Format = "format" [, "monthlist]"
Enclose the format definition in double quotes. For example:

Format definition
InputTimestamp.Format = "dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
Use the following tokens:

Date and time tokens
Token Description
yy Year, two digits.
yyyy Year, four digits.
MM Month, two digits.
M Month, one or two digits.
MMM Month, in string format. Default is standard English
three-character abbreviations, unless overridden
using the optional month list parameter.
dd Day of the month, two digits.
d Day of the month, one or two digits.
hh Hour, two digits. By default a 24-hour clock is
assumed, unless p or pp is used to specify AM/PM.
h Hour, one or two digits.
m Minutes, one or two digits.
mm Minutes, two digits.
s Seconds, one or two digits.
ss Seconds, two digits.
n Tenths of a second.
nn Hundredths of a second.
nnn Milliseconds and sub-milliseconds.
p A/P for AM/PM. This case assumes a 12-hour
clock.
pp AM/PM. This case assumes a 12-hour clock.
Note:
Month abbreviations must be comma-delimited. The time stamp format string
comparison is case-sensitive. Other evaluations are not case-sensitive.
Timestamp format examples
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
Or, months in German:


"Jan,Feb,Mär,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez"
The PI UFL interface also supports the following numeric formats:

Supported numeric formats for time
Format Description
SECONDS_GMT Number of seconds since 1970, in Universal Time
Coordinated (UTC).
SECONDS_LOCAL Number of seconds since 1970, in local time.
Both SECONDS_GMT and SECONDS_LOCAL support milliseconds.

Millisecond support
InputTimestamp.Format = SECONDS_GMT
InputTimestamp = "1405690377"
Or, with milliseconds:

InputTimestamp = "1405690377.123"
Adjustment for daylight saving time differences

If the input contains an indicator for daylight saving time (DST), define an offset for the time
using an If/Then statement.
To reflect the DST shift, subtract one hour from the time stamp as shown in the following
example:
If(Timestamp > "30-Mar-2014" AND Timestamp <= "26-Oct-2014") THEN
DSTOffset = "01:00:00"
Timestamp = Timestamp - DSTOffset
EndIf
NULL values - how Fields (variables) retain their value

Note:
Fields are NULL when declared; that is, their value is undefined.
Fields retain the values which have been assigned to them until the next assignment. That
means that when the next file (email, or stream from the Serial port) gets processed, the field
(variable) remembers the value, which has been assigned to it while processing the previous
file (stream). In order to give a field a NULL value, use the following construct:
Null values
FIELD(1) = "Value"
Value = C2-C1
[MSG] section statements

PI Connector for UFL filters incoming data to catch messages, which are assigned names. For
each message name you assign, you use the name to define a section that parses and processes
the message. Assign names to messages as follows:
[MSG]
MSG(n).Name = "MessageName"

For example:
MSG(1).Name = "HEADER"
MSG(2).Name = "DATA_LINE"
Message names are not case-sensitive. Names can contain alphanumeric characters or
underscores, but no space characters.
Filters for processing messages

For each message that you define in the [MSG] section, you must define a section for filtering
and processing the contents of the message. The section heading is the name of the message or
its entry in the message array; for example: MSG(1).
To filter specific messages, you set the FILTER attribute. Messages are filtered by matching text.
Messages are processed only by the first section that detects them, so the order in which you
define message-processing sections is significant.
Filtering is case-sensitive. To define filters based on the contents of a message, use the
following tokens.
Token Matches…
? Any single character.
* Zero or more characters.
# Any single digit (0 - 9).
[character list ] Any single character in character list. Must be
enclosed in square brackets.
[! character list ] Any single character not in the character list. Must
be enclosed in square brackets.
\ To match characters that are used for filter tokens,
for example, question marks, precede the character
with a backslash.
The following is an example of a filter that finds messages where the following are true:
• The line does not start with an exclamation point.
• Starting at position 10, the line contains the text TAG followed by any number of characters.
• Starting at position 30, the line contains the text VALUE followed by any number of
characters.
MSG(1).Filter = NOT C1=="!*" AND C10=="TAG*" AND C30=="VALUE*"
The following data line matches the filter criteria:

' 1234...TAG=mytag............VALUE=10.0
The following filter finds lines that start with "State.City.A", " State.City.B", or "State.City.C".
MSG(2).Filter = C1=="State.City.[ABC].*"
The next filter finds lines that do not begin "State.City.D", " State.City.E", or "State.City.F".
MSG(3).Filter = C1=="State.City.[!DEF].*"

Masks and wildcards for extracting data

You split a message into fields based on the position of the field, and you use masks and
wildcards to extract the required data.
Characters that are used to specify masks:
Character Matches
? Any single character.
* Zero or more characters.
# Any single digit (0 - 9).
[character string] Any single character in character string. Must be
enclosed in square brackets.
[!character string] Any single character not in character string. Must
be enclosed in square brackets.
() Indicates the data to be extracted into the field.
\ To match characters that are used for filter tokens,
for example, question marks, precede the character
with a backslash.
To extract data based on starting and ending position, specify the range using the format Cn -
Cm. For more flexibility, you can use masks and wildcards in conjunction with position
specifiers.
Examples of extracting data from messages into fields.
Example Description
FIELD(1) = C1 - C10 Extract the first ten characters from the input line.
FIELD(2) = C11 - C11(",") Extract the field that starts at character 11 and
ends before the next comma.
FIELD(3) = C11(",") - (",") Extract the field that starts after the first comma
after character 11 and ends before the next
comma.
FIELD(4) = C31 - C41("[;,:]") Extract the characters starting at position 31 up to
(but not including) the first semi-colon, comma, or
colon after position 41.
FIELD(5) = C51 - C51("[!0123456789]") Extract characters starting at position 51 up to
' (but not including) the first non-numeric
character after position 51.
For input that is formatted as orthogonal matrices of rows and columns in comma-separated
values ( .csv ) files, the simplest way to extract and assign values to individual fields without
specifying the numeric start and end points is to use the following structure for defining the
matrix. In this example, the separator is the semicolon and the construct expects exactly three
columns in the input file.
FIELD(1)=["(*);*;*"]
FIELD(2)=["*;(*);*"]
FIELD(3)=["*;*;(*)"]
The white space characters, space and tab, can be used as separators. For example:

FIELD(1)=["(*) * *"]
FIELD(2)=["* (*) *"]
FIELD(3)=["* * (*)"]
In cases where there are many commas in the . csv file, you can reduce the effort to define the
matrix by using a diagonal matrix. For example:
FIELD(1)=["(*);*"]
FIELD(2)=["*;(*);*"]
FIELD(3)=["*;*;(*);*"]
FIELD(4)=["*;*;*;(*);*"]
...
The final asterisk in each field definition addresses all commas after the field that is extracted,
which helps avoid errors caused by missed commas.
To extract a double-quoted field and strip the quotes, use a backslash to escape the quotes:
FIELD(4) = ["*,*,*\"(*)\""]
Functions and operators

Fields can be assigned values, which are the results of expressions or functions. In other words,
the resulting value on the right-hand side of an assignment is stored into the field (variable) on
the left-hand side. For example:
Value = Value + 1
FIELD(3)=FIELD(1)+FIELD(2)
FIELD(4)=UPPER(Tag)
TimeStamp=NOW()
Note:
Fields are NULL when declared; that is, their value is undefined.
The following sections describe the operations you can perform on data in fields. The data
types of all operands in the expression on the assignment's right hand side are implicitly
converted as needed.
Arithmetic and logical operators

Function Description Data Types
* / Multiply and Divide. Number, Int32, Time
+ - Add and Subtract. Number, Int32, DateTime, Time
+ or & String concatenation. String
AND Logical AND. Returns 1 if both operands Number, Int32
are non-zero, else returns 0.
OR Logical OR. Returns 1 if either operand Number, Int32
is non-zero, else returns 0.
IS NULL Checks if a field is a NULL Any
IS NOT NULL Checks if a field is not a NULL Any
Mathematical functions
ABS Absolute value Number ABS (x Number)


ACOS, ASIN, ATAN, Trigonometric functions. Angles are in Number ACOS (x Number)
ATAN2 radians.
…
COS, COSH
Number ATAN2 (x Number, y Number)
SIN, SINH
TAN, TANH
CEILING Rounds a number with a fractional Number CEILING (x Number)

portion to the next higher integer.
EXP Exponential value to base e (Euler's Number EXP (x Number)
number ≈ 2.71828).
FLOOR Largest integer less than or equal to the Number FLOOR (x Number)
given numeric expression.
LOG Logarithm to base e (Euler's number ≈ Number LOG (x Number)
2.71828).
LOG10 Logarithm to base 10. Number LOG10 (x Number)
PI Mathematical constant. Ratio of a Number PI ()
circle's circumference to its diameter. ≈
3.14159.
ROUND Rounds the value. Numbers that are Number ROUND (x Number)
right in the middle, for example 0.5, are
rounded up.
String functions
CHAR Converts an int32 ASCII code (0-255) to String CHAR (n Int)
a character.
CONCAT Concatenate two strings. String CONCAT (x String, y String)
INSTR Returns the position of the given Int INSTR (x String, substring String,
occurrence of a specified substring. start Int, occurrence Int)
Positions start with 1. Returns 0 if
specified substring is not found.
LOWER All characters lower-case. String LOWER (x String)
LEFT Returns the leftmost n characters. String LEFT (x String, n Int)
LEN Number of characters excluding leading Int LEN (x String)
and trailing blanks.
LTRIM Trim the leading blanks. String LTRIM (x String)
REPLACE Find the specified string and replace it String REPLACE (x String, findWhat
with the third parameter. String, replaceWith String)
RIGHT Returns the rightmost n characters. String RIGHT (x String, n Int)
RTRIM Trim the trailing blanks. String RTRIM (x String)
SPACE Character string consisting of n spaces. String SPACE (n Int)
SUBSTR String consisting of LEN characters String SUBSTR (x String, start Int,
starting at start position. LEN Int)
TRIM Trim leading and trailing blanks. String TRIM (x String)


UPPER All characters upper-case. String UPPER (x String)
DateTime and Time functions

The following functions extract a portion of a DateTime or Time value.
Function Data Types
DAY Int32 DAY (x DateTime)
FRACTION Number FRACTION (x DateTime)
(Extracts the sub-seconds) Number FRACTION (x Time)
HOUR Int32 HOUR (x DateTime)

Int32 HOUR (x Time)
MINUTE Int32 MINUTE (x DateTime)

Int32 MINUTE (x Time)
MONTH Int32 MONTH (x DateTime)

MONTHNAME String MONTHNAME (x DateTime)
SECOND Int32 SECOND (x DateTime)
Int32 SECOND (x Time)
WEEK Int32 WEEK (x DateTime)

YEAR Int32 YEAR (x DateTime)
Functions for extracting from well-known data formats

Extract elements from the CSV and JSON input. There are more examples on Github - PI
Connector for UFL Samples (https://github.com/osisoft/PI-Connector-for-UFL-Samples/tree/
master/REST_DATA_SENDERS%20%28REST%20SERVER%29), showing the syntax and the
use with concrete CSV and JSON structures.
Function Description
CsvGetItem("Csv_input", Function applicable in the condition part of the FOREACH()
"Delimiter") statement. It populates the predefined string variable _ITEM.
Csv_input (String) is a succession of delimited values.
Delimiter (String) can be one or more characters.
Note:
The Delimiter is case sensitive.
Returns false if the end of the delimited values was reached,

otherwise it returns true.
Example:
FOREACH(CsvGetItem(__MESSAGE, ";")) DO
Print(__ITEM)
ENDFOR

JsonGetItem("Json_input", Function applicable in the condition part of the FOREACH()
"Selector") statement. It populates the following predefined variables:
• __ITEM _Name
• __ITEM
Json_input (String) must be a valid JSON structure.
Selector (String) full path (backslash delimited) to a JSON
element containing other elements.
Note:
The Selector is case sensitive.
Returns false if the end of the JSON array or list of objects was
reached, otherwise it returns true.
Example:
FOREACH(JsonGetItem(__MESSAGE,"Channels
\CH_1[]")) DO
Print(__ITEM)
ENDFOR
JsonGetValue("Json_input", Function for extracting a single element from a JSON input.

"Selector")
Json_input (String) must be a valid JSON structure.
Selector (String) full path (backslash delimited) to a single
JSON element.
Note:
The Selector is case sensitive.
Returns the referenced JSON element in a String form. To

convert a string form to the required data type, assign the
returned string to a variable which has the required type.
Example:
Value_String = JsonGetValue(__MESSAGE,
"Elem1\Elem11")
Note:
Use the IsNumber() function to verify that the
conversion from String to Number is valid.
IF(IsNumber(Value_String) == 1) THEN
Value_Number = Value_String
ENDIF
Miscellaneous functions
Specify actions in the message-specific section that filters and processes messages.
Add(name,value) Adds a name-value pair or just a value into the collection.
Add(value)
BOS() Returns 1 (Int32) when it is the first line of the stream.

Otherwise returns 0.
Clear() Clears the collection.

DateTimeFromJulian(n) Converts a numeric Julian date to a PI time stamp. A Julian
date represents an interval of time as days and fractions of a
day since January 1, 4713 BCE Greenwich noon.
EOS() Returns 1 (Int32) when it is the last line of the stream.
Otherwise returns 0.
IsNumber("string") Determines whether the string parameter can be converted
to a numeric value. Returns 1 if a meaningful conversion
exists, 0 if not.
Now() Returns the current local time stamp in DateTime format. For
all messages read from a file, Now() returns the same time
stamp, the time when the file is opened for reading.
NowUTC() Returns the current local time stamp in UTC format. For
messages from a file, NowUTC() returns the same time
stamp, the time when the file is opened for reading.
NumberFromHex(HexNumString) Converts a string containing a hexadecimal number to
Int32.
Number16FromHex(HexNumString) Converts a string containing a hexadecimal number to
Int16.
Print(" string") Prints the string or variable value to the log.
Print(variable) Returns the variable converted to string.
SetNextMsg(MSG[,NumberOfMsgs]) Changes the order in which filters are applied to messages.

By default, filters are applied in the order in which they are
specified in the configuration file. This action redirects the
specified number of messages to the filter for the specified
message. If you omit the number of messages, all subsequent
messages are directed to the specified filter.
SkipFile() Skips the remaining lines that arrive in an input stream. This
action can be used when, for example, a certain line indicates
that the remaining rows are invalid.
SkipLines(n) Skips the specified number of lines from the input stream.
StoreInPI(), StoreEvent(), or Sends data to PI point(s). If the referenced point does not
StoreEvents() exist, the connector creates it.
StoreElement() Creates or updates a PI AF element. If the referenced element
does not exist, the connector creates it.
StoreEventFrame() Creates or updates an event frame. If the referenced event
frame does not exist, the connector creates it.
ToString(variable) Returns the variable (field name) converted to string.
Predefined variables
The following predefined string variables are recognized within the INI logic. Their meaning
summarizes the following table:
Variable name Description
__DSNAME The name of the configured data source (on the connector
administration page).
__DSDESCRIPTION Data source description.
__DSADDRESS Data source address.

Variable name Description

__ITEM_Name A string variable which is assigned the name of the selected
JSON element each time the JsonGetItem() function is
evaluated.
__ITEM A string variable which is assigned a value each time the
JsonGetItem() or CsvGetItem() functions are evaluated.
__MESSAGE The content of the current message (line).
__STREAMINFO Stream information.
For the File channel, this variable has the following format:
filename|modification date|creation date For example,
PRINT(__STREAMINFO) will return: a.txt|07-Jun-2016
04:35:39.676|03-Jun-2016 02:51:31.173
For the REST(server) channel, this variable has the following
format: Source IP Address|Port For example,
PRINT(__STREAMINFO) will return: 10.105.0.106|5687
For the REST(client) channel, this variable has the following
format: Endpoint address
For example, PRINT(__STREAMINFO) will return:
https://restcountries.eu/rest/v1/alpha/LIE
Data storage in PI Points, AF elements and Event Frames

StoreEvent or StoreInPI
To send data to PI points, use the StoreEvent() or StoreInPI() function.
• Time stamp
• Value
• Status
• Questionable flag
The syntax for this action is as follows:
StoreInPI( Tag, ElementAttribute, TimeStamp, Value[, Status, Questionable] )
StoreEvent( Tag, ElementAttribute, TimeStamp, Value[, Status, Questionable] )
Parameters:
Parameter Description Data Type
Tag Specifies the target PI point. String
(Required)
Element attribute Attribute name (data reference to PI Point) of the String

corresponding AF element. If you omit this
(Optional)
parameter, the point cannot be referenced through
an AF element.


TimeStamp Time stamp to be recorded with the value. Must be DateTime
a valid DateTime value. If you omit this parameter,
(Optional)
the current system time is recorded.
Value The value to be recorded in the target PI point. String Int32 Number
DateTime
(Required)
Status PI point status specified as a whole number Int32 or Number

corresponding to an entry in the PI System digital
(Optional)
set.
Questionable 0 for valid values, non-zero if there is an issue with Int32 or Number
the quality of the value being sent.
(Optional)
Return value Void
StoreEvents
This action sends the following data to the specified PI points
• Time stamp(s)
• Values
• Statuses
• Questionable flags
StoreEvents( TagNames, ElementAttributes, TimeStamp(s), Values[, Statuses,
Questionables] )
Parameters:
TagNames Specifies the target PI points. Collection of String
(Required)
Element attributes Attribute names (data references to PI Point) of the Collection of String
corresponding AF element. If you omit this
(Optional)
parameter, the points cannot be referenced
through an AF element.
TimeStamp(s) Time stamp (one for all tags) or a collection of time DateTime or Collection
stamps (per tag) to be recorded with the values. If of DateTime
(Optional)
you omit this parameter, the current system time is
recorded.
Values The values to be recorded in the target PI points. Collection of
(Required) • String
• Number
• Int32
• DateTime


Statuses PI point statuses specified as the collection of Collection of Int32 or
numbers corresponding to an entry in the PI Number
(Optional)
System digital set. Omit this parameter or set to 0
for valid values.
Questionable flags PI point questionable flags specified as the Collection of Int32 or
collection of numbers. Omit this parameter for Number
(Optional)
values without flags.
Return value Void
StoreElement
The StoreElement() function creates or updates a PI AF element using the following
parameters:
• Full path to a PI AF element (backslash delimited string)
• Template name
• Dynamic attributes (Tag names)
• Static attributes
Using the StoreElement() function, you can create AF elements with a specified set of
dynamic and/or static attributes. Any subsequent call to this function with the same Path-
name and the same set of dynamic and static parameters (that is - the same set of attributes
keeping the same values) will not be propagated to the PI Asset server; however, any change to
the number of parameters in collections or their types will result in the element template
update
StoreElement( Path, Template[, DynAttributes, StatAttributes] )
The square brackets indicate that those parameters are optional and can be omitted.
Parameters:
Full path to AF Back slash delimited path to an AF element. For String
element instance: Gateway\Device\Dataset
(Required)
AF template name Template name in AF for the aforementioned String

element. REM: The connector will always create a
(Required)
template for a new element and will name it
according to this parameter.
Dynamic attributes Collection of tag names (AF dynamic data Collection
references) for the aforementioned element.
(Optional)
Static attributes Collection of static attributes. Collection

(Optional)
Return value Void

Note:
Once the AF element gets created, it is always accompanied by a template that is named
according to the AF template name parameter in StoreElement(). Please make sure
that neither the AF template name nor the data types of the template attributes are
changed after the AF element creation.
StoreEventFrame
The StoreEventFrame() function creates an Event Frame using the following parameters:
• Event frame name
• Template name
• Start time
• End time or Time out
• Referenced AF element
• Dynamic attributes (Tag names)
• Static attributes
Using this function, you can create an event frame and, optionally, reference an AF element,
which has been created by the connector. Other two optional parameters are collections of
dynamic and static parameters to the event frame.
Note:
Since connector version 1.1, the event frame name will not be suffixed with current time;
as well as calls to StoreEventFrame() with the same name and start time will update
an existing event frame.
StoreEventFrame( Name, Template, StartTime, EndTime[, RefElementPath,
DynAttributes, StatAttributes] )
Parameters:
Event frame name Event frame name String
(Required)
AF template name Template name in AF for the aforementioned event String

frame. REM: The connector will always create a
(Required)
template for a new event frame and will name it
according to this parameter.
Start time Event frame start time. DateTime
(Required)
End time Event frame end time. DateTime or Time

(Optional) The end time can be omitted when it is not known
at start time; in such a case, the event frame will be
opened and any valid end time used in subsequent
calls to this event frame name will close it.
Alternatively, this parameter accepts Time data
type. If this was the case, the event frame will
automatically close after the timeout expired.


Full path to Full path to the referenced element. String
referenced AF
element
(Optional)
Dynamic attributes Collection of dynamic attributes. Collection

(Optional)
Static attributes Collection of static attributes. Collection

(Optional)
Return value Void
Code flow control (IF statement)

To define processing logic, specify the If statement as follows:
If <condition> Then <expression(s)> [Else <expression(s)>] EndIf
Specify the condition as follows:

{[NOT] <predicate> | (<condition>)}[{AND | OR} <condition>][, …]
Within the condition clause, specify the predicate as follows:

<predicate> ::= <expression>
{ == | > | < | >= | <= | <> | != } <expression>
In the predicate, specify the expression as follows:

<expression> IS [NOT] NULL
Example: If statement
If( FIELD(1) IS NOT NULL) Then
StoreInPI(FIELD(1),,NOW(),FIELD(2),,)
EndIf
FOREACH() statement
With the FOREACH() code flow control, you can loop through sets of items in the following
well-known data formats: JSON and CSV.
Below simplified example explains the principle. The syntax shows how to iterate through a
collection of comma-separated items, print them, and add the individual items to a variable of
the Collection data type.
FOREACH (CsvGetItem(__MESSAGE,",")) DO
Print(__ITEM)
Values = Add(__ITEM)
ENDFOR
The formal syntax is the following:

FOREACH(<condition>) DO <expression(s)> ENDFOR
The <condition> in the FOREACH() statement can only include one of the following functions:

• CsvGetItem
• JsonGetItem
They both return Boolean. For details about their input parameters, see Functions for
extracting from well-known data formats in Functions and operators.
The expression(s) within the body of the FOREACH() statement can be arbitrary expressions
that the UFL logic supports, including the nested FOREACH().
During each iteration, the JsonGetItem() function populates the predefined variables
__ITEM_Name and __ITEM. Both variables are strings. In order to convert the __ITEM to Number,
Int32 or DateTime, assign it to another variable which is of the required type.
Iterating through comma-separated values

Before the FOREACH() statement got introduced, dealing with comma-separated inputs with
variable numbers of items (columns) was obstructive. The reason was because the input could
contain a csv with x columns and during the next run it could have been different. With
FOREACH(), the syntax is now more flexible, it is adaptable to the varying content of the csv
input.
In order to simplify the overall syntax, the new function StoreEvents() got introduced. As
the plural indicates, it takes collections in its parameters. See also StoreEvents in Data storage
in PI Points, AF elements and Event Frames.
The following example shows how to process a csv input that contains tag names on the first
row and numeric, comma-separated values on all following rows.
Tag1,Tag2,Tag3,Tag4,Tag5,Tag6
0,1,2,3,4,5
10,11,12,13,14,15
0,1.1,2.2,3.3,4.4,5.5
[Tags]
Data.FILTER=C1=="Tag*"
TagNames = Clear()
FOREACH (CsvGetItem(__MESSAGE, ",")) DO
TagNames = Add(__ITEM)
ENDFOR
[Data]
Data.FILTER=C1=="*"
Values = Clear()
FOREACH (CsvGetItem(__MESSAGE, ",")) DO
Value_Number =__ITEM
Values = Add(Value_Number)
ENDFOR
StoreEvents(TagNames, ,NOW(), Values)

Iterating through JSON arrays and receiving a value from a JSON element
The JSON data format has many advantages such as that it is succinct, typed and
straightforward. However, for UFL, which has been optimized for working with matrixes, the
extraction logic without the looping support, was often unwieldy and cumbersome. The syntax
got simpler with the FOREACH() statement. Users can locate a certain element. If this element
is an array or a collection of similarly looking JSON objects, the construct allows for stepping
through these sets, extracting the individual items and processing them.
Example 1
This example iterates through a JSON array and forwards the extracted variables to the PI
System employing the JsonGetItem() and JsonGetValue() functions.
Note:
The whole JSON structure is forwarded to the connector JSON parsing engine through the
__MESSAGE variable.
{
"UpdateTime":"2017-04-30 23:58:10",
"VariableList": [
{ "id": "10240", "val":123.5},
{ "id": "10241", "val":83.1},
{ "id": "10242", "val":338.0}
]
}
TimeStamp = JsonGetValue(__MESSAGE, "UpdateTime")
FOREACH (JsonGetItem(__MESSAGE, "VariableList[]")) DO
ID = JsonGetValue(__ITEM, "id")
Value_Number = JsonGetValue(__ITEM, "val")
StoreEvent(ID, ,TimeStamp, Value_Number)
ENDFOR
Example 2
This example iterates through a "bare" JSON array, using the [] selector, and prints out
individual array items.
["VW","BMW","Fiat"]
FOREACH (JsonGetItem(__MESSAGE, "[]")) DO
Print(__ITEM)
ENDFOR
Configuration examples
Besides the following configuration examples, there is a set of samples on GitHub - PI
Connector for UFL Samples (https://github.com/osisoft/PI-Connector-for-UFL-Samples/tree/
master/INI_FILE_EXAMPLES).

• Data manipulation logic examples
• Action examples

Data manipulation logic examples

Data manipulation logic examples
Simple expressions with arithmetic operators.
[FIELD]
FIELD(1).Name = "StrVal"
FIELD(1).Type = "String"
FIELD(2).Name = "NumVal"
FIELD(2).Type = "Number"
Data file content: 001, Value: 1.23

Create a tag name using the '&' operator, and scale the value by a factor of 100.
[MSG(1)]
StrVal = C1 – (",")
StrVal = "TAG_" + StrVal
Extract the value and scale it:

NumVal = ["*: (*)"]
NumVal = 100 * NumVal
Mathematical function
[FIELD]
FIELD(1).Name = "NumVal1"
FIELD(2).Name = "NumVal2"
Data file content: Value1: 1.23; Value2: 2.61

[MSG(1)]
NumVal1 = ["*:(*);*"]
NumVal2 = ["*:*:(*)"]
Apply ROUND():
NumVal1 = ROUND(NumVal1)
NumVal2 = ROUND(NumVal2)
String functions
[FIELD]
FIELD(1).Name = "StrVal"
FIELD(1).Type = "String"
Replace a known error message:

[MSG(1)]
StrVal = C1 – (";")
StrVal = REPLACE(StrVal, "Invalid string part", "OK")
Sub-milliseconds
[FIELD]
FIELD(1).Name = "TimeStampVal"
FIELD(1).Type = "DateTime"
FIELD(1).Format = "dd-MMM-yyyy hh:mm:ss.nnn"
Data file content: 01-Jul-2015 08:00:00.1234; 123

PI supports time precision up to 15 microseconds.

[MSG(1)]
TimeStampVal = ["(*);*"]
Extract the number after the semicolon:

NumVal = ["*;(*)"]
DateTime math
Use "-" or "+" to conditionally adjust for daylight saving time.
FIELD(1).Name = "TimeStamp"
FIELD(1).Type = "DateTime"
FIELD(1).Format = "dd-MMM-yyyy hh:mm:ss"
FIELD(2).Name = "TimeOffset"
FIELD(2).Type = "Time"
FIELD(2).Format = "hh:mm:ss"
TimeOffset = "01:00:00"
IF(TimeStamp>="25-Mar-2014 03:00:00" AND TimeStamp<"28-Oct-2014 03:00:00") THEN
TimeStamp = TimeStamp - TimeOffset
ENDIF
Action examples
The following examples illustrate the use of actions to modify data in PI Data Archive as well as
in PI AF.
Note:
For all three actions; that is StoreEvent(), StoreElement() and
StoreEventFrame(), the following principle is applied: If a PI point, AF element, or
event frame does not exist, the Connector will create it; otherwise it will update the
corresponding values/properties/attributes.
StoreEvent() Example 1
This example shows a simple event to PI Data Archive:
Write a value of FIELD(1) to the PI tag "In:AB:001" (Float64) ' using current time.
NumVal = ["(*)"]
StoreEvent("In:AB:001", ,NOW(), NumVal)
StoreEvent() Example 2
Event with status and questionable to PI Data Archive.
FIELD(2).Name = "NumStatus"
FIELD(3).Name = "NumQuestionable"
Write a value of FIELD(1) to the PI tag "In:AB:001" (Float64) using current time. Optional
parameters to StoreEvent() are, status and questionable. Any non-zero value in the status
parameter will reflect the corresponding entry in the PI System digital set and any non-zero
value at the questionable attr. position will set on the flag questionable in PI.

NumVal = ["*,(*)"]
StoreEvent("In:AB:001", ,NOW(), NumVal, NumStatus, NumQuestionable)
StoreElement() Example 1
Simple event to PI AF with subsequent two AF elements creation. The leaf AF element will
reference the tag as its dynamic data reference.
FIELD(2).Name = "DynAttrCol"
FIELD(2).Type = "Collection"
Create two AF elements: "GatewayAB" and "GatewayAB\Input". The first one (of the
FolderType; that is, without attributes), the second one with one dynamic parameter pointing
to the previously created PI tag "In:AB:001". The name of the "GatewayAB\Input" element
dynamic attribute in AF will be "Temperature".
NumVal = ["*,(*)"]
StoreEvent("In:AB:001", "Temperature", NOW(), NumVal)
DynAttrCol = Add("In:AB:001")
StoreElement("GatewayAB")
StoreElement("GatewayAB\Input", "Measurements2", DynAttrCol)
Simple event to PI Data Archive with subsequent two AF elements creation. The leaf AF
element will reference the tag as its dynamic data reference; in addition, it will have one static
attribute.
FIELD(2).Name = "StatAttrCol"
Create two AF elements: "GatewayCD" and "GatewayCD\Input". The first one (of the
FolderType; that is, without attributes), the second one with one dynamic attribute pointing to
the previously created PI tag "In:CD:002" and one static attribute "Slot position" (Int32).
NumVal = ["*,(*)"]
StoreEvent("In:CD:002","Temperature",NOW(), NumVal)
DynAttrCol = Add("In:CD:002")
StatAttrCol = Add("Slot position", 2)

StoreElement("GatewayCD")
StoreElement("GatewayCD\Input", "Measurements2", DynAttrCol, StatAttrCol)
Simple events to PI Data Archive with subsequent two AF elements creation. The leaf AF
element will reference several tags as its dynamic data references; in addition, it will also
employ one static attribute.
FIELD(3).Name = "Geo"
Create two AF elements: "GatewayEF" and "GatewayEF\Input". The first one (of the
FolderType; that is, without attributes), the second one with three dynamic attributes, pointing
to the previously created three PI tags "In:EF:001,2,3" and two static attributes "Geo-Spatial
coordinates" and a "Name" (String).
Geo = ["(*),*"]
NumVal = ["*,(*),*"]
StoreEvent("In:EF:001","Temperature", NOW(),NumVal)
NumVal = ["*,*,(*),*"]
StoreEvent("In:EF:002","Pressure",NOW(), NumVal)
NumVal = ["*,*,*,(*)"]
StoreEvent("In:EF:003","Humidity",NOW(), NumVal)
DynAttrCol = Add("In:EF:001")
StatAttrCol = Add("Geo-Spatial coordinates", Geo)

StatAttrCol = Add("Name", "Ullersdorf")
StoreElement("GatewayEF")
StoreElement("GatewayEF\Input", "WeatherAt", DynAttrCol, StatAttrCol)

StoreEventFrame() Example 1
Simple event frame with fixed duration.
Create a plain event frame "Temperature" with ten-minute duration.
StoreEventFrame("Temperature", "EFTemp", NOW(), NOW() + "00:10:00")
Simple event frame started and ended when a condition is true.
FIELD(1).Name = "AttrCol"
FIELD(2).Name = "Tempr"
Tempr = ["(*)"]
Create an event frame "TempOver_10_oC" with one static attribute: "City".

IF( Tempr >= 10 ) THEN
AttrCol = Add("City", "Ostrava")
Open an event frame; that is, do not specify the EndTime parameter.
StoreEventFrame("TempOver_10_oC", "EFTemp", NOW(), , , AttrCol)
ENDIF
IF( Tempr < 10 ) THEN
Close it; that is, EndTime does exist (StartTime is ignored).

StoreEventFrame("TempOver_10_oC", "EFTemp", , NOW())
ENDIF

Simple event frame started and ended when a condition is true, referencing the previously-
created PI point and AF element.
FIELD(3).Name = "Tempr"
Values extraction:
Tempr = ["*,(*)"]
Write a value of "Tempr" to the PI tag "In:CD:002" (Float64).

StoreEvent("In:CD:002","Temperature",NOW(), Tempr)
Create two PI AF elements,"GatewayCD" and "GatewayCD\Input", with one dynamic and one
static attribute: "Slot position".
StatAttrCol = Add("Slot position", 2)
StoreElement("GatewayCD")
StoreElement("GatewayCD\Input", "Measurements2", DynAttrCol, StatAttrCol)
Create an event frame "TempOver_10_oC" with one static attribute, "City", referencing a
previously created element "GatewayCD\Input".
IF( Tempr >= 10 ) THEN
DynAttrCol = Clear()
StatAttrCol = Clear()
StatAttrCol = Add("City", "Ostrava")
Open an event frame; that is, no EndTime parameter.

StoreEventFrame("TempOver_10_oC", "EFTemp", NOW(), ,"GatewayCD\Input",
DynAttrCol, StatAttrCol)
ENDIF
IF( Tempr < 10 ) THEN
Close it; that is, EndTime does exist.

StoreEventFrame("TempOver_10_oC", "EFTemp", , NOW())
ENDIF
Migration from the UFL Interface

PI Connector for UFL uses the same parsing engine as the UFL Interface; however, due to
architectural changes, achieving 100% backward compatibility with the UFL interface was not
always possible. Therefore, the following topics discuss areas that require attention when users
configure PI Connector for UFL and plan to reuse existing INI files.
General considerations
PI Connector for UFL can be used for collecting data to points that have been previously
populated by the UFL Interface. For this, users just need to make sure the tag names stay the
same. By default, the PI Connector for UFL prefixes all the tag names with a string, defined in
PIPointPrefix.config.json. For more information about the point prefix, see Modify the
point prefix.
Other functionality changes to be aware of:
• Due to the fact that the PI Point database cannot be utilized for storing the configuration
settings any more, the /ALIAS definitions in Extended Descriptors are ignored. That means

that the StoreInPI(Tag, Timestamp, Value, Status, Flag, Annotation) second

parameter cannot be used for indirect referencing of PI points.
• Digital tags cannot be automatically created and the Status attribute in StoreEvent()
function accepts either strings or positive numeric values.
Both are compared against entries in the corresponding digital set.
• The Questionable flag is set by any non-zero number of the Questionable attribute in
StoreEvent/StoreInPI.
• Annotations are not supported.
• Exception reporting is not implemented.
• Logging to a specific log (OUTPUT=Path) known from the UFL interface has been dropped.
Instead, the connector specific messages are available in the Windows Event Viewer in a log
called Applications and Services\PI Connectors. Use the Print() function, see
Functions and operators, together with log level Informational for viewing the output of
the Print() function.
Removing unrecognized sections in the INI file

The [INTERFACE], [PLUG-IN], and [SETTING] sections of the UFL interface INI file are no longer
recognized. PI Connector for UFL ignores them. The individual definitions either have moved to
the connector’s administration pages or were omitted entirely. The following sections
summarize what is and what is not supported by the connector.
Section [INTERFACE]
The concept of plug-ins as implemented by the UFL Interface has been redesigned. PI
Connector for UFL still works with files in Windows directories and introduces a new
communication channel based on a REST (REpresentational State Transfer) web service. Users
choose one of these two options on the connector’s administration page.
Reading data through a serial line or through POP3 servers, is not possible with PI Connector
for UFL.
Section [PLUG-IN]
As stated in the previous paragraph, support for the Serial and POP3 plug-ins has been
removed. The following table lists only those definitions that apply to the ASCIIFiles plug-in
and explains which of the corresponding settings are used and where they can be found.
Keyword UFL Interface PI Connector for UFL
ERR File extension to be assigned to files Erroneous lines get stored in files that
that caused errors during processing. conform to the following name pattern:
The default error suffix is ERR. yyyymmdd.err.
The files are placed in: %PROGRAMDATA%
\OSIsoft\PI Connectors
\UFL.ConnectorHost\Output.
IFM Mask of the input files to be Input moved to the connector's data source
processed. When the interface runs as configuration page - the Address field.
NT service and the data files reside
on a network drive, use UNC paths to
specify the location.

Keyword UFL Interface PI Connector for UFL

IFS Specifies the order in which input Files can only be sorted by their names.
files are processed.
NEWLINE Specifies line-end characters. Input moved to the connector's data source
configuration page - the Newline field.
PFN Prepend File Name. When set, include The __STREAMINFO string variable contains
filename as the first line in the input the file name along with the creation and
stream. modification timestamps. For more details,
see the Predefined variables section under
Functions and Operators.
PFN_PREFIX Used with the PFN keyword, precedes N/A
the filename with specified text.
PURGETIME Specify the amount of time to wait For more details on how to change this
before purging processed data files. setting, see: Configure purge time/output
path/REST channel authentication.
RBP Rename Before Processing. N/A
REN Specifies the extension to be assigned For more details on how to change this
to successfully-processed input files. setting, see: Configure purge time/output
path/REST channel authentication.
WORDWRAP Breaks input line into lines of Input moved to the connector's data source
specified length. configuration page - the WordWrap field.
Section [SETTING]
The definitions in this section have been modified or omitted as shown in the following table:
Keyword UFL Interface UFL Connector
DEB Debug level. The individual debug levels, as implemented
in UFL interface, are no longer supported. In
the Diagnostics page, tab Log Configuration,
users can specify various log-levels. The
output of the Print() function goes to the
Windows Event Log, when the Informational
level option is selected.
LOCALE Specifies how the interface Input moved to the connector's data source
transforms the string representation configuration page - the Locale field.
of numbers to the native numeric
form.
MAXLOG Maximum number of log files. N/A
MAXLOGSIZE Maximum size of log files in MB. N/A
MSGINERROR Specify the path and filename for the Erroneous lines get stored in files that
log file containing lines that were not conform to the following name pattern:
successfully processed. yyyymmdd.err.
The files are placed in: %PROGRAMDATA%
\OSIsoft\PI Connectors
\UFL.ConnectorHost\Output.
OUTPUT Specify the path and filename for the For more details on how to change this
interface log file, which contains setting, see: Configure purge time/output
debugging output. path/REST channel authentication.

PI Specific Settings
The following settings are not recognized by the PI Connector for UFL.
MSG(n).EPC = "Data Type"
MSG(n).DigitalSet = "DigitalSet"
If left in place, they will be ignored.

The syntax of StoreInPI( Tag, , Timestamp, Value, Status, Flag, Annotation),
as is known from UFL Interface, has remained; however, there are two exceptions:
The Annotation parameter is not recognized. Annotations are not supported by the connector
at all; hence, if left in place, this parameter will be ignored.
The second parameter to StoreInPI( Tag,Alias,Timestamp,Value,,) function is
interpreted differently. In case of UFL Interface it pointed to the /ALIAS definition found in
extended descriptor (of PI points with the given PointSource); whereas with PI Connector for
UFL, this parameter is employed in subsequent calls to StoreElement() functions. There it is
used as a name of the dynamic AF attribute referencing a PI point created by the preceding call
to StoreInPI() function.
Changes to command line parameters

Changes to Command Line Parameters
The majority of command line parameters that are applicable to the UFL Interface are not
supported with the PI Connector for UFL. The following table describes which parameters
remained and which have been omitted.
Keyword UFL Interface UFL Connector
/am=# Archive mode. The Store mode input on the
connector's data source
configuration page represents
the closest counterpart to this
start-up parameter.
/cf=xxx.yyy Specifies the configuration file, The input moved to Config File
including full path. input on the connector's data
source configuration page.
/des=# Default error status N/A
/disablecounters Disable writing to performance N/A
counters.
/f=HH:MM:SS The /f parameter defines the The input moved to Scan Time [s]
time period between scans. input on the connector's data
source configuration page.
/host=host:port The IP address or node name and The input moved to the Server
port of the PI Server. List configuration page.
/imt Ignore missing tags, do not N/A
create them.
/lb Write events to archive in bulk N/A
for efficiency.
/lbs Write events to snapshot in bulk N/A
for efficiency.

/perf=# Specifies (in hours) how often N/A

performance summary
information is written to
performance counters.
/ps=x Specifies the point source for the N/A
points updated by the interface.
/rbo Read archive before writing N/A
value, to see if event already
exists at same timestamp.
/runonce Process existing data and exit. N/A
/tm=xxx* Tag mask. N/A
/uht_id=# Allows different instances of the N/A
UFL interface to work with a
different set of Health Tags
/utc Incoming timestamps are UTC. The input moved to Incoming
Timestamps input on the
connector's data source
configuration page.


Connector administration
Perform administrative tasks from the PI Connector Administration site.

• Verify data collection
• Verify connection from data source to connector
• Diagnostics
Verify data collection

You can use PI System Management Tools to analyze current time stamps and PI point values
to ensure the connector is collecting data.
Before you start

The connector must be running to collect data. To confirm the connector is running, from the
Start menu, run services.msc. Locate the connector service and verify the status is Running.
Procedure
1. Open PI System Management Tools and click System Management Tools > Data > Current
Values, and then click the Tag Search button.
The Tag Search window opens. Tags are the name attribute of PI points.
2. Change the Point Class value to base.
3. In the Tag Mask field, enter the product name for the connector surrounded by asterisks
(for example: *connectorname*), and then click Search.
4. Select one or more tags and click OK.
The Current Values area displays the current time stamp and value of the PI points.
Verify connection from data source to connector

From the PI Connector Administration site, open the Overview home page. In the Status of the
connector area, the status message is Connector is running and the available link is Stop
Connector.
In the Data sources area, each data source status indicates the status of the connection to the
data source.
Diagnostics
You can view diagnostic information in the PI Connector Administration site. In the left
navigation menu, click Diagnostics. Click a tab to view more information.

PI Data Servers
This PI Data Servers tab displays each PI Data Server that have been configured for the
connector. See below for descriptions of each field in the report.
Field Description
Connection status Whether the connector is currently connected to the PI Data Server.
Number of buffers The number of buffers associated with the connector.
Buffered events The number of buffered events associated with the connector.
Buffer status Whether the buffer is currently buffering data or shows the relevant
error.
Number of buffer errors Information regarding any corruption in the buffers.
PI Asset Servers
The PI Asset Servers tab provides statistics on the status and buffering performance for the
connector. See below for descriptions of each field in the report.
Field Description
Connection status Whether the connector is currently connected to the PI AF Server.
Number of buffers The number of buffers associated with the connector.
Buffered events The number of buffered events associated with the connector.
Buffer status Whether the buffer is currently buffering data.
Number of buffer errors Information regarding any corruption in the buffers.
PI Asset count The number of PI Assets currently associated with the PI Asset Server.
Message log
The Message Log tab contains important status events and errors generated by the connector.
The 1000 most recent messages logged by the current connector service process are available.
Older messages are stored in the Windows Event Viewer in a log called PI Connectors, located
in the Applications and Services Logs folder.
View message logs

Each message in the log displays its severity level, time stamp, and the message itself. Time
stamps are captured in UTC form and displayed according to the browser's time zone settings.
By default, the messages are sorted so that the newest messages are shown at the top of the
list. To reverse this behavior, click the Newest on top button. To change it back, click the button
again.
Some messages are longer than others. To facilitate fast scanning, the Message Log tab shows
each log message on a single line by default. If a message's content is too long to fit on one line,
you can hover over the message to view the full text. If you prefer to see the full content of each
message, click the Wrap Lines button and set the behavior to Always. To change it back, click
the button again to set the behavior to On Hover.

The Message Log tab queries the connector every 30 seconds to check for any new log
messages. If there are new messages, the New Messages button displays in the upper-right
corner of the tab. Click the button to reveal the new messages.
Configuring the Logging Level

By default, connectors capture only Warning and Error messages in the Message Log. To adjust
this behavior, click the Logging button and choose one of the following options:
• Verbose: captures all messages: Verbose, Information, Warning, and Error

• Information: captures most messages: Information, Warning, and Error
• Warnings: captures only Warning and Error messages
• Error: captures Error messages only
• None: Does not capture any messages in the Message Log (effectively disabling the Message
Log)
Note:
Changing the Logging level affects which messages are captured, not which messages are
displayed. The log may contain older, "Information"-level messages that were captured
prior to the change, even if you set the Logging level to "Warnings" or "Errors".
Advanced Diagnostics
The Advanced Diagnostics tab contains a list of reports that provide detailed information on
the connector. Most reports contain diagnostic information used by OSIsoft Tech Support.
Buffer Disk Usage

The Buffer Disk Usage report contains the following information about data that has been
collected but not yet sent to the target destination.
• Name
The name of the buffer disk.
• CurrentDiskUsage
The amount of disk space currently used by a buffer file. The connector allocates buffer files
on startup and when it needs additional buffers. The size of the buffer file is not an
indication of the amount of buffered data.
• MaxDiskUsage
The maximum amount of disk space for buffers.
• PercentDiskUsed
The percentage of total disk space being used.


Data buffering
Connectors are inherently capable of buffering data whenever data flows from one process
boundary to another. Buffering is always on and is not user configurable. There are no separate
processes associated with buffering. Each connector process buffers the data.
Configuration for buffering is limited to specifying the folder during setup to determine where
data is buffered, along with other state information required by the connector; otherwise, all
data is buffered in %ProgramData%\OSIsoft\Tau.
Connectors gather and group data when it is buffered, and when data is sent from connector to
PI AF or PI Data Archive. Each server gets its own buffer queue in the connector, so data sent
from connector to PI AF or PI Data Archive are buffered independently.
Connector-to-PI System buffering

Connectors are capable of buffering data to PI System servers. This includes time-series values,
tag creation, and asset creation events. Since connector buffers are capable of buffering these
different types of events, the number of events in the PI Data Server and PI Asset Server tabs
on the Diagnostics page represent a generic grouping of real-time and asset updates in PI AF.
For more information on PI System buffering events, see the Diagnostics section.
Troubleshoot buffering
Errors related to writing to PI AF or PI Data Archive are indicated with a red X icon on the
connector administration page. This indicates that there is a problem with the data flow to the
PI Server, and shows the relevant error that caused the data flow to stop.
Connector to PI Data Archive

If the connector encounters an unrecoverable PI point-based error while sending data to PI
Data Archive, it discards the errant values while continuing to send data. The connector also
logs that information with the PI point ID, timestamp, and value.
If a recoverable error occurs, the error is logged with the PI point ID, timestamp, and value. To
preserve the time integrity, the data continues to buffer until you take a corrective action. Refer
to the Message log section of this user guide for direction on corrective actions.
Connector to PI AF
The following error messages may result from issues related to buffering from a connector to
PI AF. Perform the corrective actions to resolve the issue. If the issue persists, contact OSIsoft
Technical Support though the OSIsoft Customer Portal Contact Us page (https://
customers.osisoft.com/s/contactus).

Data buffering
Message Example Cause Corrective Action

An invalid modification to an Attribute type change Change the attribute type to the
existing AF object was attempted. "New Type" displayed in the
Discarding offending event and error message and then restart
continuing processing. ID: SFO. the connector. For static
24B0D811- attributes, this will fix the
C129-4FD1-8AD1-4EED17D1FB problem. For data references,
B6. Error details: changing the attribute type
corrects the PI AF error, but the
Cannot change the type for an
underlying PI point will not
existing attribute template.
receive updates because it still
Attribute template '\\TESTPI
has an incompatible type.
\AFResources
\ElementTemplates[Airport
Monitor Connector.Fuel Tank
Farm]|StorageCapacity', Current
type 'System.Int32', New type
'System.String', Schema
'OSIsoft.Observable.AirportMonit
or.FuelTankFarmAsset 1.0.0.0'.
Cannot change an existing AF A new asset was processed with Delete the existing element and
Element's template. AF Element the same fully qualified ID as an restart the connector.
'path' with index 'ID' uses existing PI AF element but it has
template 'existingTemplate'. a different schema ID (template).
Cannot apply template
'newTemplate' representing asset
Schema 'schemaId
schemaVersion'.");
An invalid modification to an Enum entry add Delete the offending
existing AF object was attempted. enumeration set and restart the
Discarding offending event and connector.
continuing processing. ID: SFO.
24B0D811-
C129-4FD1-8AD1-4EED17D1FB
B6. Error details:
Cannot modify an existing
enumeration set. Set name
'Airport Monitor
Connector.PumpTypes'. The
number of entries in the
enumeration set has changed

Data buffering
Message Example Cause Corrective Action

An invalid modification to an Enum entry replacement Delete the offending
24B0D811-
C129-4FD1-8AD1-4EED17D1FB
B6. Error details:
'Airport Monitor
Connector.PumpTypes'.
'TestReplacement' enumeration
value cannot be added to the
enumeration set.
An invalid modification to an Enum value order changed Delete the offending

6C461BA6-DCC9-4993-
AF42-22375A10E8EA. Error
details:
'Airport Monitor
Connector.PumpTypes'. 'Screw'
enumeration value cannot be
modified. Current value 'Screw'.
New value '2'.

Data buffering

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Customer Portal Contact Us page (https://customers.osisoft.com/s/contactus). The
Contact Us page offers additional contact options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
• Product name, version, and build numbers
• Details about your computer platform (CPU type, operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details of any environment changes prior to the start of the issue
• Summary of the issue, including any relevant log files during the time the issue occurred
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.

Technical support and other resources

PI Connector For UFL 1.3.2 User Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PI Connector For UFL 1.3.2 User Guide

Uploaded by

Copyright:

Available Formats

PI Connector for UFL 1.3.

PI Connector for UFL 1.3.2 User Guide

Introduction to PI Connector for UFL........................................................................... 1

Pre-installation tasks for connectors........................................................................... 5

Install the connector................................................................................................. 13

Configure the connector........................................................................................... 19

PI Connector for UFL 1.3.2 User Guide iii

Technical support and other resources....................................................................... 71

iv PI Connector for UFL 1.3.2 User Guide

◦ listening - REST(server) mode

PI Connector for UFL 1.3.2 User Guide 1

PI Connector for UFL Architecture Diagram

Data flow example (through the REST(client) channel)

2 PI Connector for UFL 1.3.2 User Guide

PI AF structure for PI Connector for UFL data

PI Connector for UFL point data values

PI Connector for UFL 1.3.2 User Guide 3

4 PI Connector for UFL 1.3.2 User Guide

Software requirements for connectors

PI Connector for UFL 1.3.2 User Guide 5

Security best practices for PI Connector for UFL

• REST Client channel

• REST Server channel

6 PI Connector for UFL 1.3.2 User Guide

• Connection from connector to PI AF

Create the Windows account for the connector

Create the PI identity for the connector

PI Connector for UFL 1.3.2 User Guide 7

Map the Windows account to the PI identity

Enable PI Data Archive access for the PI identity

Before you start

8 PI Connector for UFL 1.3.2 User Guide

Create and configure security for the PI AF database

Enable PI AF database access for the Windows account

Before you start

The Permission for Databases window opens.

PI Connector for UFL 1.3.2 User Guide 9

Identify the administration port number

10 PI Connector for UFL 1.3.2 User Guide

Identify administration group users

PI Connector for UFL 1.3.2 User Guide 11

12 PI Connector for UFL 1.3.2 User Guide

Before you start

• Complete pre-installation tasks for connectors.

PI Connector for UFL 1.3.2 User Guide 13

1. Adds the current user to the group.

After you finish

Configure silent installation for connectors

14 PI Connector for UFL 1.3.2 User Guide

Before you start

Change connector installation settings

PI Connector for UFL 1.3.2 User Guide 15

• Reinstalling the connector software

Uninstall the connector

16 PI Connector for UFL 1.3.2 User Guide

Uninstall the connector in silent mode

PI Connector for UFL 1.3.2 User Guide 17

18 PI Connector for UFL 1.3.2 User Guide

Topics in this section

Open the PI Connector Administration site

Before you start

PI Connector for UFL 1.3.2 User Guide 19

Configure the server list