Configuring Link

After installing Link, the sample_appsettings.json file included in the installation package must be configured to your specifications.

Note: The sample_appsettings.json file is located in C:/ProgramData/Weatherford/Link.

Configuring the appsettings File for Link

The sample_appsettings.json file included in the Link installation package is configured by the user to indicate the target and source of the data to be published. After configuring it to your specifications, rename it to "appsettings.gateway.json" and store it in the following location:

C:/ProgramData/Weatherford/Link

Object and Members in the .json file

An Object in a .json file type defines the members included within the object. Each Member is considered a name/value pair. The full list of members within an object is enclosed in curly braces. The name of each member is followed by a colon and its value. Each name/value pair is delimited by a comma.

In the following example, the object ("protocol") lists four members ("type", "hostname", "port" and "keepAlive"), with each member followed by a colon and its respective value.

"protocol": {

"type": "MQTT",

"hostname": "10.97.19.106",

"port": 1883,

"keepAlive": 60,

}

Example

An example of the Link appsettings.gateway.json file is displayed below and is for sample purposes only.

Note: The following sample file is color-coded for descriptive purposes.

Click here to see an example of the file

{

"gateway": {

"passwordEncryptionKeyPath": "",

"node": {

"make": "Weatherford",

"model": "E1000"

"endpointConnections": {

"MyUIS": "MySparkPlug",

"MyVHS": "MySparkPlug",

"MyDDS": "MySparkPlug",

"MyPNT": "MyUIS"

"endpoints": [

{

"name": "MySparkPlug",

"role": "Target",

"dataFormat": {

"type": "Sparkplug",

"version": "1.0b",

"compression": "None",

"topics": {

"groupId": "Pad123",

"gatewayNodeId": "Link0001"

}

"protocol": {

"type": "MQTT",

"hostname": "10.97.19.106",

"port": 1883,

"keepAlive": 60,

"maxQueuedMessages": 5000,

"clientId": "MyClientId",

"security": {

"encryption": {

"protocol": "",

"trustedCertificatePath": "",

"clientKeystore": {

"path": "",

"password": ""

"ignoreCertificateRevocationErrors": false

"credentials": {

"user": "",

"password": ""

}

{

"name": "MyUIS",

"role": "Source",

"provides": [ "Realtime" ],

"dataFormat": {

"type": "UisService"

"protocol": {

"type": "CygNet",

"hostname": "CYGNET.UIS",

"port": 27777

"keepAlive": 0

"data" : {

"defaultPollingFreq": 1000,

"defaultQualityOfService": "Medium",

"strictPointValues": true,

"publish": [

{

"pointTag": "METERFAC1:TEMP"

"pollingFreq": 0

{

"pointTag": "METERFAC1:PRESS"

"pollingFreq": 0

{

"pointTag": "METERFAC2:TEMP"

"pollingFreq": 0

{

"pointTag": "METERFAC2:PRESS"

"pollingFreq": 0

}

]

}

{

"name": "MyVHS",

"role": "Source",

"provides": [ "History" ],

"dataFormat": {

"type": "VhsService"

"protocol": {

"type": "CygNetHistorian",

"hostname": "CygNet.VHS",

"port": 27777

"keepAlive": 0

"data": {

"defaultPollingFreq": 1000,

"pointDiscoveryFreq": 3600000, //one hour

"defaultQualityOfService": "Medium",

"strictPointValues": true,

"publish": [

{

"dynaCard": "CYGNET.UIS:WELLPILOT001",

"pollingFreq": 0

{

"dynaCard": "CYGNET.UIS:WELLPILOT002",

"pollingFreq": 0

}

]

}

{

"name": "MyDDS",

"role": "Source",

"dataFormat": {

"type": "DdsService"

"defaultFormat": "xml" // or structured

"protocol": {

"type": "CygNetDevice",

"hostname": "CygNet.DDS",

"port": 27777

"data": {

"defaultPollingFreq": 1000,

"defaultQualityOfService": "Medium",// Low, Medium, or High. For MQTT endpoints, this translates to 0, 1, or 2 QoS levels, respectively.

"publish": [

{

"device": "WELLPILOT001",

"dataGroup": "DynaCard"

{

"device": "WELLPILOT002",

"dataGroup": "DynaCard"

}

]

}

{

"name": "MyPNT",

"role": "Source",

"provides": [ "Device" ],

"dataFormat": {

"type": "PntService"

"protocol": {

"type": "CygNet",

"hostname": "CYGNET.PNT",

"port": 27777,

"keepAlive": 0

}

]

}

The different sections of the above file have been color-coded for descriptive purposes:

Black: this section defines the top-level properties of the gateway object.
Blue: this section is where the user configures the Link publisher data that will be sent to the server (target) and includes security parameters.
Green: this section represents the data coming from the CygNet UIS (source). It specifies real-time data to be published and the frequency at which it is published.
Purple: this section represents the data coming from the CygNet VHS. It specifies DynaCard data to be published and the frequency at which it is published so that it can be consumed by Foresite.
Brown: this section represents the data coming from the CygNet DDS.
Red: this section represents the CygNet PNT (source). The PNT does not publish real-time data. It is included to make the address available to acquire UDCs and values.

Properties of the sample_appsettings.json File

The following tables describe the properties in the sample_appsettings.json file used to configure Link. The tables are grouped by sections of the sample_appsettings.json file. The Type column indicates whether an item is an Object (O) or Member (M). Color-coding is used for identification purposes only.

gateway Object section

The top-level section of the sample_appsettings.json file defines the gateway object and identifies the endpoints.

File Property	Property Name	Type	Description
"gateway": {	gateway	O	The top-level object containing all of the configurable properties in Link.
"passwordEncryptionKeyPath": "",	passwordEncryptionKeyPath	M	Path to the file containing the key used to encrypt and decrypt passwords. For more information, see Link Security.
"node": {	node	O	Grouping for hardware information.
"make": "Weatherford",	make	M	Name of manufacturer.
"model": "E1000"	model	M	Model number.
"endpointConnections": { "MyUIS": "MySparkPlug", "MyVHS": "MySparkPlug", "MyDDS": "MySparkPlug", "MyPNT": "MyUIS"	endpointConnections	O	Indicates the connections between source and target endpoints.
"endpoints": [	endpoints	O	The various points of connection for the Link publisher.

Link publisher data section

The following section of the sample_appsettings.json file is where the Link publisher data that will be sent to the server (target) is configured. It includes security parameters.

File Property	Property Name	Type	Description
"name": "MySparkPlug",	name	M	The root element that defines the structure of the remaining name elements. Can be changed.
"role": "Target",	role	M	The function performed by the endpoint. Possible values: source: where the data to be published is collected from. target: where the collected data is published to (MQTT server).
"dataFormat": {	dataFormat	O	Grouping for the format of target or source data.
"type": "Sparkplug",	type	M	The type of data format. Possible values: Sparkplug AWS UisService VhsService DdsService PntService
"version": "1.0b",	version	M	The version number (1.0b) of the Sparkplug protocol. Should not be changed. Note: Should only be used when the type is "Sparkplug."
"compression": "None",	compression	M	When set to a value other than "none", Link compresses the data using the specified format, then packages the compressed data into the body of the payload, appending information to describe the content (see Payload Compression for more information). Possible values: none: payload is not compressed. zlib: payload is compressed using the zlib (RFC 1950) compression format. gzip: payload is compressed using the gzip (RFC 1952) compression format. Note: Should only be used when the type is "Sparkplug."
"topics": {	topics	O	Sent by the publisher to the server for message filtering and routing. The server then determines which subscribers will receive the message. Note: Should only be used for endpoints having a role value of "target."
"groupId": "Pad123",	groupId	M	Provides for a logical grouping of data from the publisher into the server and back out to the subscribing clients.
"gatewayNodeId": "Link0001"	gatewayNodeId	M	Uniquely identifies the topic within the infrastructure. The groupid combined with the gatewayNodeId element must be unique from any other groupid /gatewayNodeId assigned.
"protocol": {	protocol	O	Grouping for the protocol address information.
"type": "MQTT",	type	M	The type of protocol. Possible values: MQTT CygNet CygNetHistorian CygNetDevice
"hostname": "10.97.19.106",	hostname	M	For type "MQTT", the name or IP address of the server. For type beginning with "CygNet", the Site.Service.
"port": 1883,	port	M	The port connection for the target or source. When the type begins with "CygNet", refers to the domain of the Site.Service.
"keepAlive": 60,	keepAlive	M	The longest period of time that a connection between the server and client can remain open without sending a message. If no message is received in one and a half times the interval listed, the connection is closed.
"maxQueuedMessages": 5000,	maxQueuedMessages	M	When connection to the server is interrupted, published messages are held in a queue until connection is restored. When messages in the queue reach the maxQueuedMessages value, the queue discards the oldest message when a new message is published. If messages are in the queue when the Link service is terminated, the messages are saved and returned to the queue when the service is restarted. Default / minimum value is 5000. If a value lower than 5000 is entered, it automatically resets to 5000.
"clientId": "",	clientId	M	Used by MQTT clients to identify the client to the server. A client ID must only contain alphanumeric characters, with a maximum of 23 characters. If the client ID is unspecified or blank, the MQTT client will auto-generate a unique ID. Note: This property is optional.
" vendor": "",	vendor	O	Grouping for server vendor information (not displayed in sample_appsettings.json file).
" name": {	name	M	The name of the server vendor. Possible values: Amazon: must be used if the endpoint type is "AWS" (Amazon Web Services IoT Core), or the endpoint will not function properly. Note: This property is optional.
"security": {	security	O	Grouping for security settings. Options are only supported by protocol type "MQTT".
"encryption": {	encryption	O	Allows the user to establish an encrypted connection with the server. Note: This object is optional. However, the server may reject a connection if encryption is required and the member settings are not provided.
"protocol": "",	protocol	M	Should be used if the server allows/requires an encrypted connection. Possible values: TLS 1.0 TLS 1.1 TLS 1.2 Note: Choose version based on what the server supports.
"trustedCertificatePath": "",	trustedCertificatePath	M	Points to the TLS/SSL certificate required by the server. Can be used for servers that allow or require an encrypted connection.
"clientKeystore": {	clientKeystore	O	If mutual SSL/TLS authentication is required, the settings in this grouping can be used to provide the necessary client information to the server. This object is optional.
"path": "",	path	M	A path to the keystore containing the client certificate and private key in PKCS12 format (usually a .p12 or .pfx file). Note: If needed, use the OpenSSL tool to generate a .pfx file from the certificate and private key.
"password": ""	password	M	The password for the PKCS12-formatted keystore. If the keystore is not password-protected, this property can be removed or left blank.
"ignoreCertificateRevocationErrors": "",	ignoreCertificateRevocationErrors	M	Allows the user to ignore errors from the certification revocation server.
"credentials": {	credentials	O	Allows the user to set member options if the server requires user authentication. Note: This object is optional. However, the server may reject a connection if credentials are required and the member settings are not provided.
"user": "",	user	M	The username to connect to the MQTT server.
"password": ""	password	M	The password to connect to the MQTT server.

CygNet UIS section

The following section of the sample_appsettings.json file represents the data coming from the CygNet UIS (source).

File Property	Property Name	Type	Description
"name": "MyUIS",	name	M	The root element that defines the structure of the remaining name elements. Can be changed.
"role": "Source",	role	M	The function performed by the endpoint. Possible values: source: where the data to be published is collected from. target: where the collected data is published to (MQTT server).
"provides": [ "Realtime" ],	provides	M	Describes the type of data that a source endpoint provides. Possible values: Realtime: realtime point data, for endpoints using the UisService data format. Device: device data, for endpoints using the PntService data format. History: historical data, for endpoints using the VhsService data format. Note: Should only be used when the role is "source."
"dataFormat": {	dataFormat	O	Grouping for the format of target or source data.
"type": "UisService",	type	M	The type of data format. Possible values: Sparkplug AWS UisService VhsService DdsService PntService
"protocol": {	protocol	O	Grouping for the protocol address information.
"type": "CygNet",	type	M	The type of protocol. Possible values: MQTT CygNet CygNetHistorian CygNetDevice
"hostname": "CYGNET.UIS",	hostname	M	For type "MQTT", the name or IP address of the server. For type beginning with "CygNet", the Site.Service.
"port": 27777	port	M	The port connection for the target or source. When the type begins with "CygNet", refers to the domain of the Site.Service.
"keepAlive": 0	keepAlive	M	The longest period of time that a connection between the server and client can remain open without sending a message. If no message is received in one and a half times the interval listed, the connection is closed.
"data" : {	data	O	Grouping for the data to be published.
"defaultPollingFreq": 1000,	defaultPollingFreq	M	The default global frequency (in ms) used to poll data specified in publish objects if a pollingFreq value is not provided for that object. Minimum value is 200 ms.
"defaultQualityOfService": "Medium",	defaultQualityOfService	M	The value used to determine how data is sent to the server in the case of intermittent communication failure. The defaultQualityOfService is a way of specifying the quality of service (QoS) of the MQTT protocol and is used when a publish object does not specify its own quality. Possible values: Low: message delivered to the server at most once. Medium: message delivered to the server at least once. High: message delivered to the server exactly once. Note: If the endpoint type is "AWS", only Low or Medium values can be used. If a High value is configured, the value will be changed to Medium instead.
"strictPointValues": true,	strictPointValues	M	If set to "true" (default), publishing of a point is blocked and a warning is logged if its current value does not match the associated point type (e.g., if an Analog point and the value is a string). If set to "false", the point will be published, but the type shown in the Sparkplug payload will match the current value rather than the associated point type (e.g., if an Analog point and the value is a string, the Sparkplug payload will report its value type as "string").
"publish": [	publish	O	The data from the source that the publisher sends to the server.
"pointTag": "METERFAC1:TEMP"	pointTag	M	For a source endpoint that provides realtime data, the pointTag specifies the point for which data will be provided to the target endpoint. pointTag values take the form of FACILITY:UDC.
"pollingFreq": 0	pollingFreq	M	The frequency (in ms) used to poll the data specified in this publish object. If none is specified, the defaultPollingFreq is used. Minimum value is 200 ms.

CygNet VHS Section

The following section of the sample_appsettings.json file represents the data coming from the CygNet VHS and includes DynaCard data.

File Property	Property Name	Type	Description
"name": "MyVHS",	name	M	The root element that defines the structure of the remaining name elements. Can be changed.
"role": "Source",	role	M	The function performed by the endpoint. Possible values: source: where the data to be published is collected from. target: where the collected data is published to (MQTT server).
"provides": [ "History" ],	provides	M	Describes the type of data that a source endpoint provides. Possible values: Realtime: realtime point data, for endpoints using the UisService data format. Device: device data, for endpoints using the PntService data format. History: historical data, for endpoints using the VhsService data format. Note: Should only be used when the role is "source."
"dataFormat": {	dataFormat	O	Grouping for the format of target or source data.
"type": "VhsService",	type	M	The type of data format. Possible values: Sparkplug AWS UisService VhsService DdsService PntService
"protocol": {	protocol	O	Grouping for the protocol address information.
"type": "CygNetHistorian",	type	M	The type of protocol. Possible values: MQTT CygNet CygNetHistorian CygNetDevice
"hostname": "CYGNET.VHS",	hostname	M	For type "MQTT", the name or IP address of the server. For type beginning with "CygNet", the Site.Service.
"port": 27777	port	M	The port connection for the target or source. When the type begins with "CygNet", refers to the domain of the Site.Service.
"keepAlive": 0	keepAlive	M	The longest period of time that a connection between the server and client can remain open without sending a message. If no message is received in one and a half times the interval listed, the connection is closed.
"data" : {	data	O	Grouping for the data to be published.
"defaultPollingFreq": 1000,	defaultPollingFreq	M	The default global frequency (in ms) used to poll data specified in publish objects if a pollingFreq value is not provided for that object. Minimum value is 200 ms.
"pointDiscoveryFreq": 3600000, //one hour	pointDiscoveryFreq	M	The frequency (in ms) used to query the PNT service for any new DynaCard points that will be published from the VHS.
"defaultQualityOfService": "Medium",	defaultQualityOfService	M	The value used to determine how data is sent to the server in the case of intermittent communication failure. The defaultQualityOfService is a way of specifying the quality of service (QoS) of the MQTT protocol and is used when a publish object does not specify its own quality. Possible values: Low: message delivered to the server at most once. Medium: message delivered to the server at least once. High: message delivered to the server exactly once. Note: If the endpoint type is "AWS", only Low or Medium values can be used. If a High value is configured, the value will be changed to Medium instead.
"strictPointValues": true,	strictPointValues	M	If set to "true" (default), publishing of a point is blocked and a warning is logged if its current value does not match the associated point type (e.g., if an Analog point and the value is a string). If set to "false", the point will be published, but the type shown in the Sparkplug payload will match the current value rather than the associated point type (e.g., if an Analog point and the value is a string, the Sparkplug payload will report its value type as "string").
"publish": [	publish	O	The data from the source that the publisher sends to the server.
"dynaCard": "CYGNET.UIS:WELLPILOT001",	dynaCard	M	For a source endpoint that provides history data, dynaCard specifies the site service and facility portion of the full DynaCard tag for which data will be provided to the target endpoint. Each dynaCard value will resolve to a set of points that uses DynaCard UDCs (e.g., DYNLIBCRNT, DYNLIBFULL, DYNLIBPMOF, DYNLIBALRM, DYNLIBFAIL, DYNLIBIDEA, DYNLIBSTRT, DYNLIBREFR, and DYNLIBPTRN). dynaCard values take the form of SITE.SERVICE:FACILITY.
"pollingFreq": 0	pollingFreq	M	The frequency (in ms) used to poll the data specified in this publish object. If none is specified, the defaultPollingFreq is used. Minimum value is 200 ms.

CygNet DDS section

The following section of the sample_appsettings.json file represents the data coming from the DDS.

File Property	Property Name	Type	Description
"name": "MyDDS",	name	M	The root element that defines the structure of the remaining name elements. Can be changed.
"role": "Source",	role	M	The function performed by the endpoint. Possible values: source: where the data to be published is collected from. target: where the collected data is published to (MQTT server).
"dataFormat": {	dataFormat	O	Grouping for the format of target or source data.
"type": "DdsService",	type	M	The type of data format. Possible values: Sparkplug AWS UisService VhsService DdsService PntService
"defaultFormat": "xml" // or structured		M	Determines the format of the message to be published. Possible values: xml: message is sent as a raw DDS transaction. structured: each deid within the DDS transaction is parsed and broken down into individual metrics for the outgoing message. Note: These values only apply for endpoint "DdsService" and "Dynagraph" data group type. If value is not specified, the default is "structured."
"protocol": {	protocol	O	Grouping for the protocol address information.
"type": "CygNetDevice",	type	M	The type of protocol. Possible values: MQTT CygNet CygNetHistorian CygNetDevice
"hostname": "CYGNET.DDS",	hostname	M	For type "MQTT", the name or IP address of the server. For type beginning with "CygNet", the Site.Service.
"port": 27777	port	M	The port connection for the target or source. When the type begins with "CygNet", refers to the domain of the Site.Service.
"data" : {	data	O	Grouping for the data to be published.
"defaultPollingFreq": 1000,	defaultPollingFreq	M	The default global frequency (in ms) used to poll data specified in publish objects if a pollingFreq value is not provided for that object. Minimum value is 200 ms.
"defaultQualityOfService": "Medium",	defaultQualityOfService	M	The value used to determine how data is sent to the server in the case of intermittent communication failure. The defaultQualityOfService is a way of specifying the quality of service (QoS) of the MQTT protocol and is used when a publish object does not specify its own quality. Possible values: Low: message delivered to the server at most once. Medium: message delivered to the server at least once. High: message delivered to the server exactly once. Note: If the endpoint type is "AWS", only Low or Medium values can be used. If a High value is configured, the value will be changed to Medium instead.
"publish": [	publish	O	The data from the source that the publisher sends to the server.
"device": "WELLPILOT001",	device	M	The ID of the facility associated with the DynaCard data group.
"dataGroup": "DynaCard" }	dataGroup	M	The name of the data group for the data to be published. Note: All ordinals of the specified data group will be published.

CygNet PNT Section

The following section of the sample_appsettings.json file represents the CygNet PNT (source).

File Property	Property Name	Type	Description
"name": "MyPNT",	name	M	The root element that defines the structure of the remaining name elements. Can be changed.
"role": "Source",	role	M	The function performed by the endpoint. Possible values: source: where the data to be published is collected from. target: where the collected data is published to (MQTT server).
"provides": [ "Device" ],	provides	M	Describes the type of data that a source endpoint provides. Possible values: Realtime: realtime point data, for endpoints using the UisService data format. Device: device data, for endpoints using the PntService data format. History: historical data, for endpoints using the VhsService data format. Note: Should only be used when the role is "source."
"dataFormat": {	dataFormat	O	Grouping for the format of target or source data.
"type": "PntService",	type	M	The type of data format. Possible values: Sparkplug AWS UisService VhsService DdsService PntService
"protocol": {	protocol	O	Grouping for the protocol address information.
"type": "CygNet",	type	M	The type of protocol. Possible values: MQTT CygNet CygNetHistorian CygNetDevice
"hostname": "CYGNET.PNT",	hostname	M	For type "MQTT", the name or IP address of the server. For type beginning with "CygNet", the Site.Service.
"port": 27777	port	M	The port connection for the target or source. When the type begins with "CygNet", refers to the domain of the Site.Service.
"keepAlive": 0,	keepAlive	M	The longest period of time that a connection between the server and client can remain open without sending a message. If no message is received in one and a half times the interval listed, the connection is closed.