How to Configure the CygNet Collector (version 25)

The CygNet Collector connects to the CygNet VHS to log Facility and UDC combinations as tags within the Canary system. As Canary's U/I for the Collector only provides status information within the Admin, setup and configuration changes must be made directly to the SQLite database which contains its settings:

%ProgramData%\Canary\Logger\StoreAndForward\CygNetCollector\CygNetCollector.sqlite

An example database attached at the top of this article can be used to build your own connection settings if not wishing to start from the empty default database.

Configuration

1. The Collector must be installed locally to a CygNet client tool such as CygNet Explorer or its ODBC driver. See Data Collection Installation.
2. Once installed, open the SQLite database listed above or download the Sample.sqlite file. A database editor will be needed to open and make configuration changes to the file. Canary offers a portable version of DB Browser within its install for this purpose. (C:\Program Files\Canary\Canary Utilities\SQLiteDatabaseBrowser64\DB Browser for SQLite.exe)
3. Click the Browse Data tab and select the CollectorParameter table from the drop-down list.

   

    
4. The CollectorParameter table controls how data is logged from CygNet. Not all parameters are required. If a parameter is not specified, its default value will be used. Update parameters as needed.

   

   
   A description for each parameter is provided below.
   • ParentLink - Used in the process of collecting facility attributes. If particular attributes are not maintained on child assets such as individual meters, then the ParentLink parameter should be populated with the CygNet attribute to allow the Collector to walk up the CygNet hierarchy to find the parent asset that does contain the needed attributes. Used in conjunction with the ParentTypes parameter.
   • ParentTypes - Used in the process of collecting facility attributes. If particular attributes are not maintained on child assets such as individual meters, then the ParentTypes parameter should be populated with the fac_types the Collector will look for as it walks up the CygNet hierarchy to find the parent asset that does contain the needed attributes.  Used in conjunction with the ParentLink parameter.
   • PollIntervalSeconds - Number of seconds pause between each cycle of reading history value. Default value is 60.
   • CollectDataTimeoutSeconds - Number of seconds the collector will make consecutive calls for history values before exiting the function. Default value is 30.
   • FacilityIntervalHours - Interval in hours to run the process that scans for new facilities and tags. Default value is 12.
   • FacilityPollOffsetMinutes - Number of minutes past the top of the hour to run the process that scans for new facilities and tags. Default value is 15.
   • BackfillDays - The number of days to backfill history from CygNet VHS when a new tag is either added into the configuration or discovered for the first time. Default value is 7.
   • RemoteViewsIdentityApiToken - Used to authenticate to the Identity service when the Collector is on a different machine than the Historian. This token will need to be created within the Identity service and linked to a Canary user who has read permissions on the Historian view within the Identity>Security>Tag Security screen. See How to Create an API Token.
   • UnreliableToNoData - Controls what quality to write on a TVQ when an unreliable status flag is received from CygNet. Default value is True.
   • UnreliableToUncertain - Controls what quality to write on a TVQ when an unreliable status flag is received from CygNet. Default value is False.
   • NanToNoData - Allows the Collector to write a No Data Value when a NaN value is received from CygNet. Default value is False.
   • UseExternalPropertyStorage - Controls whether tags in the active SaF session will have the SaF store any property values in an external database instead of writing to the Historian directly. Default value is False.
   • ExtendData - Controls whether tags in the active SaF session will have time extension enabled in the Historian. Default value is False.
   • MaxTagsPerDataSet - Controls the number of tags the Collector will place in a DataSet before creating a subsequent DataSet. This parameter is utilized when the DataSet is defined in the Division table with an * at the end (i.e. CygNetData*) to indicate dynamic DataSet creation. Default value is 25000.
   • TagToTrace - If trying to troubleshoot a specific tag, this parameter can be set to output additional debug messages to our message log when the debug verbosity is enabled for the CygNetCollectorService source.
   • UseAlternateHistoryValidation - This parameter determines the method for validating each tag against the VHS. By default, the Collector issues the GetNamesandStatistics call to CygNet to return all the tags and their range of data so that validation can be done to determine if this is a tag Canary wants to actively log. On larger CygNet systems this call can take an exceptionally long time to return and so an alternative method of validation can be used where a call per tag is made to CygNet. This, of course, means a lot more round-trip calls into CygNet but ends up being quicker in the long run. Default value is False.
   • IncludeInactiveFacilities - When reading the facility table from CygNet, this parameter determines whether inactive facilities that have not interfaced previously will be permitted to be processed and added into the tag list generated by the Collector. Default value is False.
   • UseExpandedCanaryTagName - By default, the Canary tag name is a concatenation of facility_id + "_" + UDC. There are situations where a facility_id can exist or move between CygNet facility services such as UIS and OPCIS (each service has it's own facility entry in CygNet). This causes conflicts because the same Canary tag name could be generated twice. UseExpandedCanaryTagName ensures a unique tag name will be created because the facility_service will now become part of the tag name with the following syntax: CygNet_site.facility_service::facility_id + "_" + UDC. Default value is False.
5. Navigate to the Division table to add a division (site). Divisions are independent of one another within the Collector and can be stopped/started without interrupting other divisions. Divisions can be site-based or asset-based depending on what is intuitive for the user. The example shown below is asset-based where Wells and Meters are split into two divisions.

   

   • Division Key - used in other tables to reference the division
   • Description - division name which is displayed in the Status screen of the CygNet Collector tile in the Canary Admin
   • SourceServer - leave blank
   • SourceDomain - CygNet's internal domain number for routing
   • SourceName - site name
   • Historian - destination server name where data will be sent
   • DataSet - name of the DataSet where data will be stored in the Historian. If an asterisk (*) is appended to the name, the Historian will create multiple DataSets and increment the count by one whenever the MaxTagsPerDataSet parameter is exceeded. (e.g. Wells, Wells2, Wells3, etc.)
   • Enabled - 1 (Enabled), 0 (Disabled)
6. Navigate to the AssetTag table. From here, the user can define the facilities and their UDC's they wish to log. Within the Collector, the SourceAssetType is equivalent to the Fac_type within CygNet. The user has the option of listing the facility and its UDC's explicitly or using a wildcard (*) in the UDC column to log all UDC's of the given Fac_type. The screenshot below shows both methods.

   

   • DivisionKey - number used to reference the division from the Division table
   • SourceAssetType - Fac_type in CygNet
   • UDC - tag name of Fac_type to be logged
   • *Description - description of tag that will be stored as a property in Canary
   • *EngUnits - engineering units of a tag that will be stored as a property in Canary
   • PollRate - deprecated
   • LowAlarmOffset - deprecated
   • HighAlarmOffset - deprecated
   • Transform - expression used to transform a value coming from CygNet. Use keyword value as the variable in the expression (e.g. value*10).

     *Optional - These are used to overwrite the Description and EngUnits attributes that may be available in CygNet. If wishing to use what is stored in CygNet, these can be configured in the next step using the AssetProperties table.

7. Navigate to the AssetProperties table. From here the user can configure the properties (attributes) they want to attach to the tags that will be logged in the Historian.

   

   • DivisionKey - number used to reference the division from the Division table. If left blank, the Collector will log the properties for all configured divisions.
   • SourceTable - a CygNet record type (Facility, Point, Point.Tag)
   • SourceColumn - a CygNet attribute name
   • PropertyDescription - the Canary property name which will get assigned to the attribute value
   • ParentProperty - if the attribute is not maintained at the facility record the Collector can walk the CygNet hierarchy to acquire the attribute value from a parent object
   • TableReference - a CygNet table lookup that allows the Collector to reference a more readable description.
8. Optional - Navigate to the AdditionalTags table. From here the user can add unique tags that would not be picked up by the AssetTag table from Step 6.

   

   • DivisonKey - number used to reference the division from the Division table where the tag will be included
   • SourceTag - full tag path of the UDC as it is listed in CygNet
   • *Description - description of tag that will be stored as a property in Canary
   • *EngUnits - engineering units of a tag that will be stored as a property in Canary

     *Optional - These are used to overwrite the Description and EngUnits attributes that may be available in CygNet. If wishing to use what is stored in CygNet, these can be configured in the AssetProperties table.

9. Optional - Navigate to the ExcludedUDCs table. This table only needs to be configured when using the wildcard method in Step 6 if wishing to exclude certain UDC's that would otherwise be included.

   

   • DivisionKey - number used to reference the division from the Division table. This should be the same key that the wildcard AssetType from the AssetTag table is using.
   • UDC - name of the UDC to be excluded
10. Click the Write Changes button to save the database and close.

    

     
11. If using the Sample.sqlite file to make changes, rename it to CygNetCollector.sqlite and replace the default database located in %ProgramData%\Canary\Logger\StoreAndForward\CygNetCollector.
12. Restart the CygNet service from Canary Admin>Services tile.
13. Navigate to the CygNet Collector tile and enable the session(s) listed.