Run the PI to CONNECT Agent Configuration Utility

Use the PI to CONNECT Agent Configuration Utility to set up and configure AF server and Data Archive data sources before creating a data transfer. After installing or upgrading a PI to CONNECT Agent, use the utility to select a source AF server or Data Archive, view connection details, create AF and PI mappings, set data privacy settings, and register the agent.

Note: A connection to CONNECT with the post-installation utility cannot be established if the system time is not correct. Additionally, you will not be able to connect to CONNECT if Internet Explorer Enhanced Security Configuration is enabled. For more information, see Disable IE enhanced security.

The following table provides descriptions of the fields shown in the configuration utility. The image shows the AF server selected, but the fields are similar when a Data Archive server is selected.

Open the PI to CONNECT Agent Configuration Utility

The PI to CONNECT Configuration Utility opens after you install or upgrade a PI to CONNECT Agent. You can open the PI to CONNECT Agent Configuration Utility at any time to change server connections and other settings after initial setup.

To open the PI to CONNECT Agent Configuration Utility:

1. Select Start > AVEVA > PI to CONNECT Agent Configuration Utility, and then select Yes to confirm.

2. Select Sign in to CONNECT.

   This opens https://signin.connect.aveva.com/login in a web browser for login. After successful authentication, return to the configuration utility.

3. Select your site from the Sites dropdown list.

4. (Optional) In the Agent Description box, enter a descriptive name for the agent.

5. (Optional) To display the hostname in the portal, select the Opt-in to publishing PI to CONNECT Agent Hostname option.

6. Select Continue.

Add an AF server

Optionally, add an AF server to the utility to be able to use it in data transfers. The utility validates an AF server connection to ensure the version of PI Asset Framework (AF) installed on the AF server supports the features required for transfers.

To add an AF server:

7. Open the PI to CONNECT Agent Configuration Utility.

8. In the PI to CONNECT Configuration Utility window, select the AF button.

   Note: If a Data Archive server was added first, select Add Asset Framework Server on the left side of the window instead.

9. In the AF Server Name field, enter the name of the AF server, and then select Add Server.

   The utility displays the server details.

   Note: Once an AF server has been added, the utility scans the configured AF server for referenced Data Archives. As the utility finds Data Archives, they are shown in the Detected Data Archives list. You can select and add the desired Data Archive. You do not have to wait for the scan to complete. You can also select Add Data Archive Server on the left and manually enter the name of the Data Archive if you do not want to wait for the scan.

10. Select one of the Data Archives listed under Detected Data Archives, and then select Add Selected Data Archive.

    Note: You can select Add Data Archive Server on the left at any time to add a Data Archive before the scan completes.

11. Review the AF source server details to ensure they are correct:

    • AF server name, version, and ID

    • IP address

    • Connection status and timeout

12. (Optional) To add an alternate display name, select the pencil icon, type an alternate name, select Set Display Name and then select Close. CONNECT stores the alternate display name instead of the actual AF server name. See Usage of server names and alternate display names within CONNECT.

13. (Optional) To change the length of time the agent checks for a server connection before timing out, select the pencil icon next to Connection Timeout.

14. (Optional) To check that the connection to the AF server is working, select Test Connection.

15. (Optional) To delete a server connection, select Remove Server, then select Remove AF Server to confirm.

16. To keep the current AF server configuration settings and restart the agent, select Save.

    Note: After you save the AF server configuration settings, you need to select a default Data Archive in PI System Explorer to resolve substitution references for AF element attributes.

Usage of server names and alternate display names within CONNECT

The AF server name, or its alternate display name, displays on the Agents page within CONNECT and is referenced in the path of an asset's metadata, which is visible in Asset Explorer (__Path).

The Data Archive name, or its alternate display name, appears in the Agents page within CONNECT, and is used in the StreamIds created by a transfer. StreamIds have the format PI_[DataArchiveServerName]_[PIPointIDNumber].

Note: Setting an alternate display name for a Data Archive must be done before the initial start of a transfer. StreamIds are immutable. Once a stream is built, to change it you must delete all the original streams, configure the alternate display name, and restart the transfer.

Select the default Data Archive in PI System Explorer

You need to specify the default Data Archive, also referred to as the default data server, for the PI System and PI AF database after setting an AF server. By default, PI AF databases inherit the PI AF Server's local default data server. See Find the default Data Archive server for more information.

To select the default Data Archive:

17. Open PI System Explorer on the client machine.

18. Select File > Server Properties.

19. In the PI AF Server Properties window, select the data server from the Default Data Server dropdown list.

20. Select Apply, then select OK to save the selection.

21. Close PI System Explorer.

Create an AF mapping

You can assign an AF mapping to an AF identity. AF mappings enable a specific service account assigned to an AF identity in PI System Explorer to read and transfer AF element and AF attribute data. You can also edit mappings with the utility.

Note: The user account that launches the utility must have permission to create mappings.

To create an AF mapping:

22. Open the PI to CONNECT Agent Configuration Utility.

23. Select the pencil icon next to AF Mapping.

24. In the Configure AF Mapping window, select an identity and select Create.

    The AF mapping is created for the selected identity.

    Note: If an AF mapping has been created with another tool, a warning is displayed.

25. Select Close to return to the utility.

Add a Data Archive

If you plan on transferring AF server data, we recommend you add an AF server first, because the PI to CONNECT Agent Configuration Utility will detect automatically the Data Archive servers that are referenced by AF server. This allows you to select the source Data Archive that contains the PI points you want to transfer. However, you can also add a Data Archive without adding an AF server.

Note: There is a one-to-one (1:1) Data Archive to PI to CONNECT Agent constraint for PI to CONNECT transfers. If your AF server references multiple Data Archives, only one Data Archive can be selected and configured for the transfer.

The list of available Data Archive servers is based on the servers referenced by AF elements on the AF server you selected. If you are upgrading an agent, the PI to CONNECT Agent Configuration Utility maintains the previously selected Data Archive configuration.

Note: If you are not adding an AF server, select the Data Archive icon on the first page of the PI to CONNECT Agent Configuration Utility.

To add a Data Archive:

26. Open the PI to CONNECT Agent Configuration Utility.

27. In the PI to CONNECT Agent Configuration Utility window, select the Data Archive Server button.

    Note: If an AF server was added first, select Add Data Archive Server on the left side of the window instead.

28. In the Data Archive Server Name field, enter the name of the Data Archive server, and then select Add Server.

    The Data Archive connection is added and details about the newly added Data Archive are displayed.

29. Review the following details for the Data Archive:

    • Server name, version, and server ID

    • IP address

    • Connection status and timeout

30. (Optional) To add an alternate name, select the Alternate Display Name pencil icon, type an alternate name, select Set Display Name and then select Close.

    Note: Setting an alternate display name for a Data Archive must be done before the initial start of a transfer. See Usage of server names and alternate display names within CONNECT.

31. (Optional) To change the length of time the agent checks for a server connection before timing out, select the pencil icon next to Connection Timeout (sec).

32. (Optional) To confirm that the connection to the Data Archive is working, select Test Connection.

33. (Optional) To remove the configured Data Archive, select Remove Server, then select Remove Data Archive to confirm.

34. To retain the current Data Archive configuration, select Save.

Create a PI mapping

PI mappings enable access to data stored on a Data Archive by service accounts assigned to a PI identity. PI mappings can be created for a PI identity, user, or group. Accounts assigned to a PI identity can read and transfer PI point data to CONNECT. For more information, see What are PI identities and mappings?. You can also edit mappings with the utility.

Note: The user account used to launch the utility must have permissions to create mappings.

To create a PI mapping:

35. Open the PI to CONNECT Agent Configuration Utility.

36. Select the Data Archive server on the left side of the window.

37. Select the pencil icon next to PI Mapping.

    The Configure Mapping window opens.

    

38. Select an identity for the PI mapping, then select Create.

    The PI mapping is created for the selected PI identity, PI group, or PI user.

    Note: If a PI mapping has already been created with another tool, a warning is displayed.

39. Select Close to return to the utility, and then select Save in the utility.

Set data privacy and edit an agent description

Use the PI to CONNECT Agent Settings to change the data privacy setting and to edit the descriptive name for the agent. This description appears where the agent is referenced and allows you to search by agent description. The data privacy setting controls whether the host name of a Data Archive is published and displayed in CONNECT. By default, host names are not published. If you opt to have a host name published, it appears in the portal on the Agents page.

40. Open the PI to CONNECT Agent Configuration Utility.

41. To open the PI to CONNECT Agent Settings window, select the pencil icon to the right of Agent Service Account.

42. To publish the hostname, select the Opt-in to publishing... option under Data Privacy.

43. (Optional) In the PI to CONNECT Agent Description field, enter a descriptive name for the agent.

44. To save your selections, select Ok, and then select Save in the utility.

List of agent states

After saving in the PI to CONNECT Agent Configuration Utility, it may take a few minutes for the PI to CONNECT Agent to register with CONNECT. The table below lists the various states that may appear under Agent State in the PI to CONNECT Configuration Utility.