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 data services 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 data services 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 > PI to CONNECT Agent Configuration Utility, and then select Yes to confirm.

2. Select Connect to CONNECT data services.

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

   

3. Select a namespace from the CONNECT Namespace dropdown list.

4. (Optional) In the Agent Description field, 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 data services stores the alternate display name instead of the actual AF server name. See Usage of server names and alternate display names within CONNECT data services.

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 data services

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

The Data Archive name, Data Archive Collective name, or the alternate display name if one exists, appears in the PI Agents page within CONNECT data services. Stream IDs created by a transfer have the format PI_[IDPrefix]_[PIPointIDNumber], where the IDPrefix is the alternative display name, if it exists, or the Data Archive name or Data Archive Collective name.

Note: We recommend setting an alternate display name for a Data Archive before the initial start of a transfer because stream IDs and asset IDs cannot be changed. If the name is changed after streams and assets have been created, their IDs do not change.

The maximum character length for an AF server alternate display name is 63 and the maximum character length for the Data Archive alternate display name is 86. The difference is due to added information. Both fields start with a maximum of 100 characters because Asset Id and Stream Id have a 100-character limit. To form an Asset Id, the agent adds an underscore and a 36-character GUID to an AF server alternate display name, allowing 63 characters (100-37) for the alternate display name. To form a Stream Id, the agent prepends the Data Archive alternate display name with PI_ and appends _[PIPointIDNumber] (maximum of 10 characters), allowing 86 characters (100-14) for the alternate display name.

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 used to launch 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 settings 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 or Data Archive Collective

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 data transfers. If your AF server references multiple Data Archives, only one Data Archive can be selected and configured for the transfer. However, multiple Data Archives can be added for usage reporting purposes.

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 or Data Archive Collective:

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 or Data Archive Collective, and then select Add Server.

    Note: For a collective to be fully supported, you must specify the collective name rather than the primary/secondary node individually.

    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

    • Collective Name, Collective ID, Collective Members (if it is a collective)

    • IP address

    • Connection status and timeout

30. (Optional) To enable the server for data transfer, select Enable Data Transfer option.

    Note: You can add multiple Data Archive servers for reporting usage as part of the PI Aggregate Tag licensing model. Only one archive or collective can be used for data transfer.

31. (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: We recommend setting an alternate display name for a Data Archive before the initial start of a transfer because the prefix for stream and asset IDs is created from the display name. If it is changed after streams and assets have been created, that prefix does not change.

32. (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).

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

34. (Optional) To remove the configured Data Archive, select Remove Server.

35. 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 data services. 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:

36. Open the PI to CONNECT Agent Configuration Utility.

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

38. Select the edit icon next to PI Mapping.

    The Configure Mapping window opens.

    

39. 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.

40. 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 edit the descriptive name for the agent and to change the data privacy setting. 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 data services. By default, host names are not published. If you opt to have a host name published, it appears in the portal on the PI Agents page as shown below:

41. Open the PI to CONNECT Agent Configuration Utility.

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

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

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

45. 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 data services. The table below lists the various states that may appear under Agent State in the PI to CONNECT Configuration Utility.

Video Tutorial: Configure a PI to CONNECT Agent

Video Transcript (Select to expand)