Install the PI to CONNECT Agent

The PI to CONNECT Agent can be installed as part of the PI Server installation kit, or as a standalone install.

Configure access to Data Archive Security tables, PI point data, and optional AF server

For the following Data Archive security configuration items, you will need to enable read access to the PI identity, PI group, or PI user that the PI to CONNECT Agent is connecting as.

• Archive data (PIARCDATA Security table)

• The PI points configuration table (PIPOINT Security table)

• The PI points and data to be transferred

For AF Server security configuration, ensure the AF Identity that the PI to CONNECT Agent is connecting as has read access to the elements and attributes to be transferred.

Note: Due to a known issue, the Run As user of the PI to CONNECT Agent must have read access to all AF databases, even databases for which no data is being transferred. Otherwise, the agent will encounter issues with AF indexing, causing the agent to stop collecting data on restart.

Install the PI to CONNECT Agent

This section describes how to install the PI to CONNECT Agent using the standalone PI to CONNECT Agent installation kit. For guidance on installing the PI to CONNECT Agent with the PI Server installation kit, refer to the PI Server 2023 (or greater) documentation.

To install the standalone PI to CONNECT Agent:

1. In the left pane, select Data Collection > PI Agents.

2. From the agents dropdown list, select PI to CONNECT Agents.

3. Select Download Agent.

4. On the Agent Installer Download window, select Download. When the download completes, select Cancel to close the window.

5. Open the downloaded PI to CONNECT Agent installation file, then select Yes to confirm running the installation file.

   The Welcome page of the PI to CONNECT Agent window opens.

6. On the Welcome page, select Next.

   The Service Account page opens.

   Note: The Service Account page is shown only for new installations.

7. On the Service Account page, select the service account type for the connection:

   • NT Service – Select NT account for the service to run as NT SERVICE\PIToDataHubAgent.

     Note: The service account retains the previous name of the product, PIToDataHubAgent, to avoid issues when upgrading from a previous agent version.

   • This account – Specify a username and password (domain\account) for the Run as user for the PI to CONNECT Agent service.

     Note: For Windows integrated security, the service account selected on this page determines the account to use for PI identity mapping and AF mapping. The Run as user can be changed after the installation from the Windows Service control panel. Changing this account may require configuration changes to PI mapping and AF mapping, but changing the account will not otherwise affect the access to local resources needed by the agent.

8. Select Install.

9. After the agent is installed, select Close.

   The PI to CONNECT Agent Configuration Utility opens. See Run the PI to CONNECT Agent Configuration Utility for instructions.

   Note: Agent registration is not complete until you add and configure a Data Archive server in the PI to CONNECT Agent Configuration Utility.

Silent installation

There are several use cases for doing a silent installation of the PI to CONNECT Agent.

• Silent installations are useful for automating deployments.

• Silent installations avoid browser logins to PI to CONNECT. A new, interactive installation requires that Internet Explorer Enhanced Security be disabled, and some customers cannot disable this security.

• Installations of the PI to CONNECT Agent on Windows Server Core Operating System are supported only with silent installation.

Silent installs for new installations

These instructions can be used to set up a new installation of the PI to CONNECT Agent, configured with connections to CONNECT data services, without needing to run the PI to CONNECT Configuration Utility. The command lines in this section can be used for upgrades as well, but tenant, namespace, Data Archive, and AF server cannot be changed during an upgrade. Command line parameters related to this will be ignored. For the minimal command line needed for upgrades, see Silent installs for upgrades or minimal new installations.

10. Create a client-credentials client with an assigned role of Tenant Contributor and add a secret. See Add a client-credentials client.

    Note: Be sure to securely store the Client Id and Client Secret where you can access it again, because this is the only time you will have access to this information. You will need this information to proceed with the silent install.

11. Find the TENANTID and record it where you can access it.

    When you log into CONNECT data services, the TENANTID is visible in the URL. It is the long GUID.

    https://datahub.connect.aveva.com/tenant/[YOUR TENANT ID]/dashboard

    Alternatively, select Developer Tools > API Console and the TENANTID displays in the Full Path.

    uswe.datahub.connect.aveva.com/api/v1/Tenants/[YOUR TENANT ID]/Namespaces.

12. Find the NAMESPACE Id and record it where you can access it.

    Select Developer Tools > API Console and select GET. The NAMESPACE Id appears as the Id field in the response.

    

    Note: If you have multiple namespaces, you will have multiple entries in this list. Be sure to select the NAMESPACE Id of the namespace where you want PI to CONNECT Agent to send data.

13. Record the GATEWAYBASEURL for your region where you can access it. See Regional endpoints.

14. Open a Windows command prompt as an administrator.

15. Change to the folder where you have downloaded the PI to CONNECT Agent installation kit.

16. If you do not need to configure an Alternate Display Name for your Data Archive or AF servers, enter the following command. This command will immediately register the agent with the actual Data Archive name specified by the DATAARCHIVE command line argument.

    Note: The TENANTID, CLIENTID, CLIENTSECRET, and NAMESPACE keywords are required for the agent to connect to CONNECT data services at installation time. All keywords are case sensitive. SERVICEACCOUNT and SERVICEPASSWORD provide the Run As user and password, respectively, for the PI to CONNECT Agent service.

    PItoDataHubAgent_SetupKit.exe TENANTID=[tenantid] CLIENTID=[clientid] CLIENTSECRET=[clientsecret] NAMESPACE=[namespaceID] GATEWAYBASEURL=[regionalendpoint] DATAARCHIVE=[DataArchiveName] AFSERVER=[AFServerName] SERVICEACCOUNT=[user] SERVICEPASSWORD=[password] AGENTDESCRIPTION="Your Description" /quiet

17. If you need to configure an Alternate Display Name for your Data Archive or AF servers, enter the following command. The Data Archive, AF server, and Alternate Display Names will be configured in a subsequent step.

    Note: The TENANTID, CLIENTID, CLIENTSECRET, and NAMESPACE keywords are required for the agent to connect to CONNECT data services at installation time. All keywords are case sensitive.

    PItoDataHubAgent_SetupKit.exe TENANTID=[tenantid] CLIENTID=[clientid] CLIENTSECRET=[clientsecret] NAMESPACE=[namespaceID] GATEWAYBASEURL=[regionalendpoint] AGENTDESCRIPTION="Your Description" /quiet

18. If you need to configure a proxy for the agent, enter the following command.

    PItoDataHubAgent_SetupKit.exe TENANTID=[tenantid] CLIENTID=[clientid] CLIENTSECRET=[clientsecret] NAMESPACE=[namespaceID] GATEWAYBASEURL=[regionalendpoint] DATAARCHIVE=[DataArchiveName] AFSERVER=[AFServerName] SERVICEACCOUNT=[user] SERVICEPASSWORD=[password] AGENTDESCRIPTION="Your Description" PROXYADDRESS=[ProxyAddress] PROXYUSERNAME=[ProxyUser] PROXYPASSWORD=[ProxyPassword] /quiet

19. Check that the PI to CONNECT Agent service is running.

    From an administrative command prompt, run the command net start | find "PI" and verify that "PI to CONNECT Agent" is in the list.

20. Check the event logs for any errors.

    1. Right-click on Start and select Event Viewer.

    2. Select Applications and Services Logs and double-click PI to CONNECT.

    For Windows Server Core operating systems, you can connect to the Event Viewer remotely.

21. Check the setup logs.

    1. Open a command prompt and navigate to %ProgramData%\OSIsoft\Setup\log.

    2. Logs can be listed from oldest to newest with the command dir /od.

22. (Optional) Configure an Alternate Display Name for Data Archive and/or AF server.

    Note: For a silent install an Alternate Display Name is required to use the PI to CONNECT Agent Configuration Utility.

    1. Open an administrative command prompt and navigate to %ProgramData%\OSIsoft\PItoOCS.

    2. Run the command notepad.exe appsettings.json.

    3. To specify an alternate display name for the Data Archive, add the following AlternateDisplayName entry. If you did not specify AFSERVER and DATAARCHIVE on the command line above, you will need to add the server names in this step as well as specifying the alternate display name.

       "PIDataArchiveServerNames": [

       {

       "Name": "MyActualDataArchiveServerName",

       "AlternateDisplayName": "AlternateDisplayName",

       "ConnectionTimeout": 10,

       "OperationTimeout": 60

       }

       ],

    4. To specify an alternate display name for AF, add the following AlternateDisplayName Entry:

       "PIAssetFrameworkServerNames": [

       {

       "Name": "MyActualAFServerName",

       "AlternateDisplayName": "AlternateDisplayName",

       "ConnectionTimeout": 10

       }

       ],

    5. Save the changes and restart the PI to CONNECT Agent service from an administrative command prompt with the commands:

       net stop pitodatahubagent

       net start pitodatahubagent

23. Verify your agent is visible on the PI Agents page in the portal and ready to configure.

Silent installs for upgrades or minimal new installations

These instructions can be used to upgrade the PI to CONNECT Agent. They can also be used for a new installation of the PI to CONNECT Agent, but the installation requires configuration with the PI to CONNECT Agent Configuration Utility for the new installation.

24. Open a Windows command prompt as an administrator.

25. Change to the folder where you have downloaded the PI to CONNECT Agent installation kit.

26. Run the following command:

    PItoDataHubAgent_SetupKit.exe /quiet

The above command is sufficient for an upgrade. For a new installation, run the PI to CONNECT Agent Configuration Utility to register the PI to CONNECT Agent after the silent installation completes.

Video Tutorial: Download and install a PI to CONNECT Agent

Video Transcript (Select to expand)