Managing Collector Instances

About Managing Collector Instances Using Configuration Hub

Collectors are used to collect data from various sources and send it to Historian. For a list of collectors and their usage, refer to About Historian Data Collectors.

After you install collectors and Remote Management Agent, the following artefacts will be available:

Executable files: These files are required to add a collector instance.
Instances of the following collectors:
- The iFIX collector
- The iFIX Alarms & Events collector
- The OPC Classic Data Access collector for CIMPLICITY
- The OPC Classic Alarms and Events collector for CIMPLICITY
These instances will be created only if iFIX and/or CIMPLICITY are installed on the same machine as the collectors.
The Remote Collector Management agent: Provides the ability to manage collectors remotely.

You can then add a collector instance. This section describes how to add a collector instance using Configuration Hub. You can also add a collector instance using the RemoteCollectorConfigurator utility, which does not require you to install Web-based Clients.

Note: Using Configuration Hub, you cannot add comments, enable the debug mode, pause data collection, resume data collection, modify, or delete an instance of offline collectors. In addition, you cannot compress network messages. You can, however, add or delete the collector instance using the Collector Manager utility at a command prompt.

Send Data to a Historian Server

Before you begin

Install collectors.
For an iFIX collector, ensure that iFIX is running in a Windows-service mode. For more information, refer to About Adding an iFIX Collector Instance Using Configuration Hub.
If the destination of a collector is an Azure IoT Hub device, ensure that the device is running.

This topic describes how to add a collector instance and send data to a on-premises Historian server using Configuration Hub. You can also add a collector instance using the RemoteCollectorConfigurator utility, which does not require you to install Web-based Clients.

Procedure

Access the system to which you want to add a collector instance.
Select Collectors.
A list of collectors in the system appears.
Select .
The Add Collector Instance: <system name> window appears, displaying the Collector Selection section. The MACHINE NAME field contains a list of machines on which you have installed collectors.
In the MACHINE NAME field, select the machine in which you want to add a collector instance.
In the COLLECTOR TYPE field, select the type of the collector whose instance you want to add, and then select Get Details.
The INSTALLATION DRIVE and DATA DIRECTORY fields are disabled and populated.
Select Next.
The Source Configuration section appears, populating the hostname of the collector machine.
Select Next.
The Destination Configuration section appears. By default, Historian Server is selected, and the DESTINATION HISTORIAN SERVER field is disabled and populated with the value you provided in the MACHINE NAME field in the Collector Selection section.
If you want to use a local user account to connect to the Historian server, select Next. Or if you want to use a specific user account, enter values in the USERNAME and PASSWORD fields, and then select Next.
The Collector Initiation section appears.
In the COLLECTOR NAME field, enter a unique collector name.
In the RUNNING MODE field, select one of the following options.
- Service - Local System Account: Select this option if you want to run the collector as a Windows service using the credentials of the local user (that is, the currently logged-in user). If you select this option, the USERNAME and PASSWORD fields are disabled.
- Service Under Specific User Account: Select this option if you want to run the collector as a Windows service using a specific user account. If you select this option, you must enter values in the USERNAME and PASSWORD fields. If you have enabled the Enforce Strict Collector Authentication option in Historian Administrator, you must provide the credentials of a user who is added to at least one of the following security groups:
  - iH Security Admins
  - iH Collector Admins
  - iH Tag Admins
If you choose the first option, you can also configure the collector to start automatically when you start the computer, or, in the case of iFIX collectors, whenever you start iFIX.
Select Add.
The collector instance is created.
Specify the tags whose data you want to collect using the collector. Alternatively, you can use an offline configuration file to specify the tags.
The collector sends data to the Historian server.

Send Data to AWS IoT Core

Procedure

Access the AWS Management Console page.
Search and select IoT Core.
The AWS IoT page appears.
Create a policy allowing the permissions that you want to grant on your device (for example, iot:Connect, iot:Publish, iot:Subscribe, iot:Receive). For the resource, provide the topic name. If, however, you want to use all topics, enter *.
Create a thing, linking it with the policy that you have created.
Download the certificates and key files for the device to communicate. In addition, download the root CA certificate.

Important: This is mandatory, and it is the only time you can download the certificates.
In the left navigation pane, select Settings.
Make a note of the endpoint that appears.
Access Configuration Hub.
Select Collectors.
A list of collectors in the system appears.
Select .
The Add Collector Instance: <system name> window appears, displaying the Collector Selection section. The MACHINE NAME field contains a list of machines on which you have installed collectors.
In the MACHINE NAME field, select the machine in which you want to add a collector instance.
In the COLLECTOR TYPE field, select a collector type (except the File collector and the Server-to-Server collector), and then select Get Details.
The INSTALLATION DRIVE and DATA DIRECTORY fields are disabled and populated.
Select Next.
The Source Configuration section appears, populating the hostname of the collector machine.
Select Next.
The Destination Configuration section appears.

In the CHOOSE DESTINATION field, select MQTT, and then provide values as described in the following table.


Field	Description
HOST ADDRESS	Enter the endpoint that you have noted down.
PORT	Enter 8883.
CLIENT ID	Enter the thing name.
TOPIC	Enter the MQTT topic to which you want the collector to publish data. A value is required. For information on topic names, refer to https://docs.aws.amazon.com/iot/latest/developerguide/topics.html.
USERNAME	Enter any value. Since we will use a certificate-based authentication, username and password will not be used; however, you must still enter a value.
PASSWORD	Enter any value. Since we will use a certificate-based authentication, username and password will not be used; however, you must still enter a value.
CA SERVER ROOT FILE	Enter the path of the root CA certificate file that you have downloaded.
CLIENT CERTIFICATE	Enter the path of the device certificate that you have downloaded.
PRIVATE KEY FILE	Enter the path of the private key file that you have downloaded.
PUBLIC KEY FILE	Enter the path of the public key file that you have downloaded.
CHOOSE CONFIGURATION	Select the type of the configuration to specify the tags whose data you want to collect. Select one of the following options: Historian Configuration: Select this option if you want to add the tags manually using Historian Administrator. If you select this option, the CONFIGURATION HISTORIAN SERVER field appears. Offline Configuration: Select this option if you want to provide the tag names using the offline configuration file instead of adding tags manually. By default, this file is located in the following location: `<installation folder of Historian>`\GE Digital\`<collector name>`

Select Next.
The Collector Initiation section appears.
In the COLLECTOR NAME field, enter a unique collector name.
In the RUNNING MODE field, select one of the following options.
- Service - Local System Account: Select this option if you want to run the collector as a Windows service using the credentials of the local user (that is, the currently logged-in user). If you select this option, the USERNAME and PASSWORD fields are disabled.
- Service Under Specific User Account: Select this option if you want to run the collector as a Windows service using a specific user account. If you select this option, you must enter values in the USERNAME and PASSWORD fields. If you have enabled the Enforce Strict Collector Authentication option in Historian Administrator, you must provide the credentials of a user who is added to at least one of the following security groups:
  - iH Security Admins
  - iH Collector Admins
  - iH Tag Admins
If you choose the first option, you can also configure the collector to start automatically when you start the computer, or, in the case of iFIX collectors, whenever you start iFIX.
Select Add.
The collector instance is created.
Specify the tags whose data you want to collect using the collector. While creating the collector instance, in the CHOOSE CONFIGURATION field in the Destination Configuration field:
- If you have selected Historian Configuration, access Historian Administrator, and manage the tag configuration. For information, refer to Configure Tags.
- If you have selected Offline Configuration, modify the offline configuration file of the collector. By default, this file is available in the following location: <installation folder of Historian>\GE Digital\<collector name>. For information, refer to Creating Offline Configuration XML file.
Access AWS IoT Core, and in the left pane, select Test.
The MQTT test client page appears.
Subscribe to the topic to which the collector is publishing data, and then select Subscribe.
The messages received from the topic appear, indicating that the collector is sending data to the AWS IoT device.
AWS supports a payload of maximum 128 KB. Therefore, if the message size is greater than 128 KB, create a registry key named CloudMaxSamplesPerMsg for the collector instance, and decrease the value to 700 or less. If, however, you want to send more data in a message, we recommend that you create another collector instance and send data to another thing resource in AWS.
Tip: To find out the message size, modify the collector instance and set the log level to 3 or more.
Create a VPC destination or an HTTP destination for the messages.
Monitor the data that you have collected.

About Sending Data to Azure IoT Hub

The following conditions apply when you send data to Azure IoT Hub:

Data in Azure IoT Hub is stored for maximum seven days, after which it is deleted from the hub. Therefore, you must consume the data within seven days. Based on your requirement, you can store it in a relevant Azure storage. You can then use Azure functions or streaming analytics to analyse the data.
The data sent to Azure IoT Hub is in the JSON format with UTF-8 encoding. To reduce the message size and avoid repetition of tag properties, the tag values are in the format of the KairosDB data points: [{"<tag name>":"Cloud_GCYSS3X2E.Simulation00001","<time stamp, tag value, and quality>":[[1586260104000,132560.203125000,3]]}

Before add a collector instance to send data to Azure IoT Hub, you must perform the following steps:

Set up an Azure IoT Hub account.
Note: To choose the correct Azure IoT Hub based on your requirement, refer to https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-quotas-throttling
Create devices in Azure IoT Hub. These devices store the data received from a collector. We recommend that you create one device per collector instance.

Access the Details of a Collector Instance

Procedure

Access the system linked to the collector instance whose details you want to view.

Select Collectors.

A list of collectors linked to the system appears, displaying the following columns:


Column	Description
COLLECTOR NAME	The name of the collector instance. If you select the link in this column, the details of the collector instance appears.
COMPRESSION	The effectiveness of collector compression. If the value is low, you can increase the compression deadbands to pass fewer values and thus increase the effect of compression.
CONFIGURATION	The source of the tag configuration for the collector. Contains one of the following values: HISTORIAN: Indicates that tags are configured using Historian Administrator. OFFLINE: Indicates that tags are configured using an offline configuration file.
MACHINE	The name of the machine on which the collector is installed.
OUT OF ORDER	The total number of out-of-order samples for the collector.
OVERRUNS	The total number of data events not collected. In normal operation and under normal conditions, this value should always be zero. If the value is not zero, which indicates that data is being lost, you must take steps to reduce peak load on the system by increasing the collection interval.
REDUNDANCY	Indicates whether collector redundancy is enabled, which decreases the likelihood of lost data due to soft- ware or hardware failures. For information, refer to Collector Redundancy.
REPORT RATE	The average rate at which the collector is sending data. This is a general indicator of load on the collector.
STATUS	The status of the collector. Contains one of the following values: Started Stopped Running Paused
TAG COUNT	The number of tags for which the collector collects data.
VERSION	The version number of the collector.

Note: You can add, reorder, and remove columns from the table. For instructions, refer to Common Tasks in Configuration Hub.

Select the row containing the collector whose details you want to access.
The details of the collector appear in the main section, and a summary appears in the Details section.
Note: If the Details section does not appear, in the upper-right corner of the page, select , and then select Details.

Add a Collector Instance

Before you begin

Install collectors.
For an iFIX collector, ensure that iFIX is running in a Windows-service mode. For more information, refer to About Adding an iFIX Collector Instance Using Configuration Hub.
If the destination of a collector is an Azure IoT Hub device, ensure that the device is running.

About this task

Before you begin using a collector, you must add an instance of the collector. You can add multiple instances of the same collector or instances of multiple collectors where you have installed the collectors. To add multiple instances of a collector, perform the steps provided in this topic once again.

Note: When you install collectors, if iFIX and/or CIMPLICITY is installed on the same machine as the collectors, instances of the following collectors are created automatically:

The iFIX collector
The iFIX Alarms & Events collector
The OPC Classic Data Access collector for CIMPLICITY
The OPC Classic Alarms and Events collector for CIMPLICITY

You can begin using these collectors, or create more instances as needed.

This topic describes how to add a collector instance using Configuration Hub. You can also add a collector instance using the RemoteCollectorConfigurator utility, which does not require you to install Web-based Clients.

Procedure

Access the system to which you want to add a collector instance.
Select Collectors.
A list of collectors in the system appears.
Select .
The Add Collector Instance: <system name> window appears, displaying the Collector Selection section. The MACHINE NAME field contains a list of machines on which you have installed collectors.
In the MACHINE NAME field, select the machine in which you want to add a collector instance.
In the COLLECTOR TYPE field, select the type of the collector whose instance you want to add, and then select Get Details.
The INSTALLATION DRIVE and DATA DIRECTORY fields are disabled and populated.
Select Next.
The Source Configuration section appears. For an OPC collector, the source configuration is automatically populated. And, if you have selected File Collector, the Destination Configuration section appears. If that happens, skip to step 8.
In the HISTORIAN SOURCE SERVER field, enter the machine name of the source server from which you want the collector to collect data. As needed, enter values in the USERNAME and PASSWORD fields to connect to the server.
For cloud collectors, a different set of fields appear. In that case, enter values in the available fields.
Select Next.
The Destination Configuration section appears.
In the CHOOSE DESTINATION field, select the destination to which you want the collector to send data. By default, Historian Server is selected.
Depending on the destination you have selected, provide values in the available fields, and then select Next.
The Collector Initiation section appears. The COLLECTOR NAME field is disabled and populated.
In the RUNNING MODE field, select one of the following options.
- Service - Local System Account: Select this option if you want to run the collector as a Windows service using the credentials of the local user (that is, the currently logged-in user). If you select this option, the USERNAME and PASSWORD fields are disabled.
- Service Under Specific User Account: Select this option if you want to run the collector as a Windows service using a specific user account. If you select this option, you must enter values in the USERNAME and PASSWORD fields. If you have enabled the Enforce Strict Collector Authentication option in Historian Administrator, you must provide the credentials of a user who is added to at least one of the following security groups:
  - iH Security Admins
  - iH Collector Admins
  - iH Tag Admins
If you choose the first two options, you can also configure the collector to start automatically when you start the computer, or, in the case of iFIX collectors, whenever you start iFIX.
Select Add.
The collector instance is added, and appears in the Collectors list. A shortcut is created for each instance of the following collectors so that you can open them at a command prompt:
- The iFIX collector
- The iFIX Alarms and Events collector
- The OPC Classic Alarms and Events collector
- The OPC Classic DA collector
- The OPC Classic HDA collector

What to do next

Specify the tags whose data you want to collect using the collector. In the CHOOSE CONFIGURATION field in the Destination Configuration field,

If you have selected Historian Configuration, access Historian Administrator, and manage the tag configuration. For information, refer to Configure Tags.
If you have selected Offline Configuration, modify the offline configuration file of the collector. By default, this file is available in the following location: <installation folder of Historian>\GE Digital\<collector name>. For information, refer to Creating Offline Configuration XML file.

Modify a Collector Instance

About this task

This topic describes how to modify a collector instance using Configuration Hub. You can also modify a collector instance using the RemoteCollectorConfigurator utility, which does not require you to install Web-based Clients.

Note:

If the status of a collector instance in unknown, you cannot modify it.
You cannot modify the instance of an offline collector.

Procedure

Access the system that contains the collector instance that you want to modify.
Select Collectors.
A list of collectors in the system appears.
In the COLLECTOR NAME column, select the link that corresponds to the collector instance that you want to modify.
The details of the collector appear.
Select , and then select Edit.
Depending on the destination of the collector, provide values in the available fields.

Note: You cannot modify the destination of the collector.
Select Save. Or, if the changes you have made requires restarting the collector, select Save & Restart. Normally, it is required when you change values in the INSTANCE CONFIGURATION section.
Note: For collectors earlier than version 9.0:
- You cannot modify the details in the INSTANCE CONFIGURATION section.
- Some of the details, such as the collector type, do not appear.

Add a Comment to a Collector Instance

About this task

This topic describes how to add a comment to a collector instance.

Note:

You cannot modify or delete comments.
You cannot add comments to offline collectors.

Procedure

Access the collector instance to which you want to add a comment.
The details of the collector appear in the Details section, along with a list of comments.
In the Details section, in the text box below COMMENTS, enter your comment, and then select ADD COMMENT.
The comment is added to the collector instance.

Access a Comment on a Collector Instance

Procedure

Access the collector instance whose comments you want to access.
The details of the collector appear in the Details section, along with a list of comments.
If you want to search for a comment, enter the search criteria in the Search box. You can also filter the comments based on a date and time range by selecting the values in the FROM and TO boxes.
The comments are filtered based on the search criteria.

Collector Instance Fields

This topic provides information on the collector instance fields. These fields are categorized based on the destination of the collector.

Destination: Historian Server


Field	Description
DESTINATION SERVER	The machine name of the Historian server to which you want the collector to send data.
USERNAME	The username to access the Historian server.
PASSWORD	The password to access the Historian server.

Destination: Predix Timeseries


Field	Description
CLOUD DESTINATION ADDRESS	The URL of a data streaming endpoint exposed by the Predix Time Series instance to which you want to send data. Typically, it starts with ???wss://???. This value is used as part of the interface name and default tag prefix of the collector. Your Predix Time Series administrator can provide this URL.
IDENTITY ISSUER	The URL of an authentication endpoint for the collector to authenticate itself and acquire necessary credentials to stream to the Predix Time Series. In other words, this is the issuer ID of the UAA instance that you want to use to connect to Predix Time Series. Typically, it starts with https:// and ends with ???/oauth/token???.
CLIENT ID	Identifies the collector when interacting with Predix Time Series. This is equivalent to the username in many authentication schemes. The client must exist in the UAA instance identified by the identity issuer, and the system requires that the `timeseries.zones. {ZoneId}.ingest` and `timeseries.zones.{ZoneId}.query` authorities are granted access to the client for the Predix Zone ID specified. Your Predix Time Series administrator can provide this information.
CLIENT SECRET	The secret to authenticate the collector. This is equivalent to the password in many authentication schemes.
ZONE ID	Unique identifier of the instance to which the collector will send data.
PROXY	Identifies the URL of the proxy server to be used for both the authentication process and for sending data. If the collector is running on a network where proxy servers are used to access web resources outside of the network, then you must provide the proxy server settings. However, it does not affect the proxy server used by Windows when establishing secure connections. As a result, you must still configure the proxy settings for the Windows user account under which the collector service runs.
PROXY USERNAME	The username to connect to the proxy server.
PROXY PASSWORD	The password to connect to the proxy server.
DATAPOINT ATTRIBUTES	The attributes or parameters related to a datapoint that you want the collector to collect. Select Add Attributes to specify the attributes. You can add maximum five attributes for each collector instance.
CHOOSE CONFIGURATION	The type of the configuration to specify the tags whose data you want to collect. Select one of the following options: Historian Configuration: Select this option if you want to add the tags manually using Historian Administrator. If you select this option, the CONFIGURATION HISTORIAN SERVER field appears. Offline Configuration: Select this option if you want to provide the tag names using the offline configuration file instead of adding tags manually. By default, this file is located in the following location: `<installation folder of Historian>`\GE Digital\`<collector name>`
CONFIGURATION HISTORIAN SERVER	The host name of the machine from which you want to access Historian Administrator to add the tags manually for the collector. This field appears only if you have selected Historian Configuration in the CHOOSE CONFIGURATION field.

Destination: Azure IoT Hub


Field	Description
DEVICE CONNECTION STRING	Identifies the Azure IoT device to which you want to send data. Enter a value in the following format: `HostName=<value>;DeviceId=<value>;SharedAccessKey=<value>`
TRANSPORT PROTOCOL	The protocol that you want to use to send data to Azure IoT Hub. Select one of the following options: HTTP MQTT AMQP MQTT_OVER_WEBSOCKETS AMQP_OVER_WEBSOCKETS For information on which protocol to use, refer to Protocols and Port Numbers.
PROXY	Identifies the URL of the proxy server to be used for both the authentication process and for sending data. If the collector is running on a network where proxy servers are used to access web resources outside of the network, then you must provide the proxy server settings. However, it does not affect the proxy server used by Windows when establishing secure connections. As a result, you must still configure the proxy settings for the Windows user account under which the collector service runs.
PROXY USERNAME	The username to connect to the proxy server.
PROXY PASSWORD	The password to connect to the proxy server.
CHOOSE CONFIGURATION	The type of the configuration to specify the tags whose data you want to collect. Select one of the following options: Historian Configuration: Select this option if you want to add the tags manually using Historian Administrator. If you select this option, the CONFIGURATION HISTORIAN SERVER field appears. Offline Configuration: Select this option if you want to provide the tag names using the offline configuration file instead of adding tags manually. By default, this file is located in the following location: `<installation folder of Historian>`\GE Digital\`<collector name>`
CONFIGURATION HISTORIAN SERVER	The host name of the machine from which you want to access Historian Administrator to add the tags manually for the collector. This field appears only if you have selected Historian Configuration in the CHOOSE CONFIGURATION field.

Destination: MQTT

Tip: To establish an MQTT connection with Alibaba Cloud, refer to https://www.alibabacloud.com/help/doc-detail/73742.htm. To generate a password to connect to Alibaba Cloud, use the utility located here.


Field	Description
HOST ADDRESS	The host name of the MQTT broker to which you want the collector to send data. A value is required.
PORT	The port number of the MQTT broker.
CLIENT ID	The name of the MQTT client. A value is required and must be unique for an MQTT broker.
TOPIC	The MQTT topic to which you want the collector to publish data. A value is required.
AUTO REFRESH	Indicates whether you want to automatically refresh the authentication token when it expires. If you switch the toggle off, you must manually provide the token as soon as it expires. If you switch the toggle on, you must provide details of the required certificates.
USERNAME	Enter the username to connect to the MQTT broker.
PASSWORD	Enter the password to connect to the MQTT broker.
CA SERVER ROOT FILE	Enter the path of the CA server root file that you want to use to connect to the MQTT broker.
CLIENT CERTIFICATE	Enter the path to the client certificate that you want to use to connect to the MQTT broker.
PRIVATE KEY FILE	Enter the path to the private key file that you want to use to connect to the MQTT broker.
PUBLIC KEY FILE	Enter the path to the public key file that you want to use to connect to the MQTT broker.
CHOOSE CONFIGURATION	The type of the configuration to specify the tags whose data you want to collect. Select one of the following options: Historian Configuration: Select this option if you want to add the tags manually using Historian Administrator. If you select this option, the CONFIGURATION HISTORIAN SERVER field appears. Offline Configuration: Select this option if you want to provide the tag names using the offline configuration file instead of adding tags manually. By default, this file is located in the following location: `<installation folder of Historian>`\GE Digital\`<collector name>`
CONFIGURATION HISTORIAN SERVER	The host name of the machine from which you want to access Historian Administrator to add the tags manually for the collector. This field appears only if you have selected Historian Configuration in the CHOOSE CONFIGURATION field.

Protocols and Port Numbers

The following table provides a list of protocols that are available to send data to Azure IoT Hub, guidelines on which protocol to choose, and the port number that each protocol uses.


Protocol	When to Use	Port Number
HTTP	Use this protocol if the data that you want to send is not large and/or the default ports for the other protocols are not available.	80
MQTT	MQTT is lightweight compared to AMQP, and is widely used. Use this protocol if you want to send data using low bandwidth and/or you do not want to connect to multiple devices using the same connection.	8883
AMQP	AMQP is more reliable compared to other protocols. It sends data in batches, and hence, the network traffic is less compared to that of MQTT. Use this protocol if you want to send a large amount of data from multiple collectors frequently.	5671
MQTT over web sockets	MQTT is lightweight compared to AMQP, and is widely used. In addition, communication using web sockets is more reliable and secure. Use this protocol if you want to send data using low bandwidth and securely.	443
AMQP over web sockets	AMQP is more reliable compared to other protocols. It sends data in batches, and hence, the network traffic is less compared to that of MQTT. In addition, communication using web sockets is more reliable and secure. Use this protocol if you want to send a large amount of data from multiple collectors frequently and securely.	443

Delete a Collector Instance

About this task

If you no longer want to use a collector instance to collect data, you can delete it. When you delete a collector instance, the Windows service for the collector, the Registry folder, and the buffer files are deleted as well.

This topic describes how to delete a collector instance using Configuration Hub. You can also delete a collector instance using the RemoteCollectorConfigurator utility, which does not require you to install Web-based Clients.

Note: When you delete an offline collector instance, the corresponding configuration file is not deleted. However, if another collector instance of the same interface name is created, the existing configuration file is replaced by a template configuration file.

Procedure

Access the system that contains the collector instance that you want to delete.
Select Collectors.
A list of collectors in the system appears.
In the COLLECTOR NAME column, select the link that corresponds to the collector instance that you want to delete.
The details of the collector appear.
Select , and then select Delete.
A message appears, asking you to confirm that you want to delete the collector instance.
If you want to delete the tags as well, select the Delete associated tags as well check box.
Select Delete.
The collector instance is deleted.