Configure data endpoints

Save PDF

Last UpdatedFeb 04, 2025
5 minute read

Adapters can egress data to one or more data endpoints simultaneously. While it depends on the use case, customers can configure a single adapter to send to egress data to multiple PI Servers, a PI Server and CONNECT data services, or to multiple CONNECT data services namespaces.

Complete the following steps to configure egress endpoints.

Use the PUT method in conjunction with the http://localhost:5590/api/v1/configuration/OmfEgress/dataendpoints REST endpoint to initialize the configuration.
Using a text editor, create an empty text file.
Copy and paste an example configuration for egress endpoints into the file.

For sample JSON, see the Examples section below.
Update the example JSON parameters for your environment.

For a table of all available parameters, see Egress endpoints parameters table.
Save the file. For example, ConfigureEgressEndpoints.json.
Open a command line session. Change directory to the location of ConfigureEgressEndpoints.json.
To initialize the egress endpoints configuration, send the ConfigureEgressEndpoints.json content as request body by Postman (which uses the PUT method) to http://localhost:5590/api/v1/configuration/OmfEgress/dataendpoints.

Note: If you installed the adapter to listen on a non-default port, update 5590 to the port number in use.

Alternatively, you can use the following edgecmd command:

edgecmd -cid omfegress set DataEndpoints -file ./ConfigureEgressEndpoints.json

For a list of other REST operations you can perform, like updating or replacing an egress endpoints configuration, see REST URLs section below.

Egress endpoint parameters

The following parameters are available for configuring egress endpoints:

Parameter	Required	Type	Description
id	Optional	string	Unique identifier Allowed value: any string identifier Default value: new GUID
endpoint	Required	string	Destination that accepts OMF v1.2 messages. Supported destinations include CONNECT data services and AVEVA PI Server. Allowed value: well-formed http or https endpoint string Default: null
username	Required for AVEVA PI Server endpoint	string	Basic authentication to the PI Web API OMF endpoint Basic authentication to the PI Web API OMF endpoint AVEVA PI Server: Allowed value: any string Default: null Note: If your username contains a backslash, you must add an escape character, for example, OilCompany\TestUser as OilCompany\\TestUser If neither Username nor ClientID is supplied, it will use Negotiation instead (i.e., Kerberos, NTLM)
password	Optional for AVEVA PI Server endpoint	string	Basic authentication to the PI Web API OMF endpoint AVEVA PI Server: Allowed value: any string or {{<secretId>}} (see How to reference secrets) Default: null
clientId	Required for CONNECT data services endpoint	string	Authentication with the CONNECT data services OMF endpoint Allowed value: any string, can be null if the endpoint URL schema is HTTP Default: null
clientSecret	Required for CONNECT data services endpoint	string	Authentication with the CONNECT data services OMF endpoint Allowed value: any string or {{<secretId>}} (see How to reference secrets); can be null if the endpoint URL schema is HTTP Default: null
debugExpiration	Optional	string	Enables logging of detailed information to disk for each outbound HTTP request pertaining to the egress endpoint. The value represents the date and time this detailed information should stop being saved. Examples of valid strings representing date and time: UTC: yyyy-mm-ddThh:mm:ssZ, Local: yyyy-mm-ddThh:mm:ss. For more information, see Troubleshooting. Default: null
tokenEndpoint	Optional for CONNECT data services endpoint	string	Retrieves an CONNECT data services token from an alternative endpoint Allowed value: well-formed http or https endpoint string Default value: null
validateEndpointCertificate	Optional	boolean	Disables verification of destination certificate. Note: Only use for testing with self-signed certificates. Allowed value: true or false Default value: true

Special characters encoding

The adapter encodes special characters used in the data selection StreamId parameter string before sending it to configured endpoints. The encoded characters look as follows:

Special character	Encoded character
*	%2a
'	%27
`	%60
"	%22
?	%3f
;	%3b
\|	%7c
\	%5c
{	%7b
}	%7d
[	%5b
]	%5d

Examples

The following examples are valid egress configurations:

Egress data to CONNECT data services

[

{

"id": "CONNECT data services",

"endpoint": "https://<CONNECT data services OMF endpoint>",

"clientId": "<clientid>",

"clientSecret": "<clientsecret>"

}

]

Egress data to Edge Data Store

[

{

"id": "Edge Data Store",

"endpoint": "http://<Edge Data Store endpoint>"

}

]

Note: In order to send data from an adapter to an Edge Data Store instance, both products must be installed on the same device. This includes module-to-module scenarios.

Egress data to PI Web API

[

{

"id": "PI Web API",

"endpoint": "https://<pi web api server>:<port>/piwebapi/omf/",

"userName": null,

"password": null

}

]

Egress data to PI Web API using a valid secret Id

See How to reference secrets for more information on how to use a secret Id.

[

{

"id": "PWA_OIDC",

"endpoint": "https://PIWebAPIEndpoint/piwebapi/omf",

"userName": null,

"password": null,

"clientId": "oidc-client",

"clientSecret": "{{System.HealthEndpoints.PWA_OIDC.ClientSecret}}",

"debugExpiration": null,

"tokenEndpoint": "https://AIMEndpoint/identitymanager/connect/token",

"validateEndpointCertificate": false

}

]

Egress data to PI Web API using negotiate

When egressing data to PI Web API using negotiate, the user account running the adapter (i.e., the service account) is sent to PI Web API.

[

{

"id": "PI Web API",

"endpoint": "https://<pi web api server>:<port>/piwebapi/omf/"

}

]

Note: Egressing data to PI Web API using negotiate only works if your adapter is installed on a Windows OS.

REST URLs

Relative URL	HTTP verb	Action
api/v1/configuration/omfegress/DataEndpoints	GET	Gets all configured egress endpoints
api/v1/configuration/omfegress/DataEndpoints	DELETE	Deletes all configured egress endpoints
api/v1/configuration/omfegress/DataEndpoints	POST	Adds an array of egress endpoints or a single endpoint. Fails if any endpoint already exists
api/v1/configuration/omfegress/DataEndpoints	PUT	Replaces all egress endpoints
api/v1/configuration/omfegress/DataEndpoints	PATCH	Allows partial updating of configured endpoints. Note: The request must be an array containing one or more endpoints. Each endpoint in the array must include its Id.
api/v1/configuration/omfegress/DataEndpoints/{Id}	GET	Gets configured endpoint by Id
api/v1/configuration/omfegress/DataEndpoints/{Id}	DELETE	Deletes configured endpoint by Id
api/v1/configuration/omfegress/DataEndpoints/{Id}	PUT	Updates or creates a new endpoint with the specified Id
api/v1/configuration/omfegress/DataEndpoints/{Id}	PATCH	Allows partial updating of configured endpoint by Id

Egress execution details

After configuring an egress endpoint, egress is immediately run for that endpoint. Egress is handled individually per configured endpoint. When data is egressed for the first time, types and containers are egressed to the configured endpoint. After that only new or changed types or containers are egressed. Type creation must be successful in order to create containers. Container creation must be successful in order to egress data.
If you delete an egress endpoint, data flow immediately stops for that endpoint. Buffered data in a deleted endpoint is permanently lost.
Type, container, and data items are batched into one or more OMF messages when egressing. As per the requirements defined in OMF, a single message payload will not exceed 192KB in size. Compression is automatically applied to outbound egress messages. On the egress destination, failure to add a single item results in the message failing. Types, containers, and data are egressed as long as the destination continues to respond to HTTP requests.

AVEVA™ Adapter for DNP3