Health endpoints
- Last UpdatedFeb 20, 2025
- 3 minute read
You can configure Client Failover Service to produce and store health data at a designated health endpoint. You can use health data to ensure that your Client Failover Service is running properly and that data flows to the configured OMF endpoints.
Configure health endpoint
A health endpoint designates an OMF endpoint where adapter health information is sent. You can configure multiple health endpoints.
Complete the following steps to configure health endpoints. Use the PUT method in conjunction with the https://<host>:<port>/api/v1/configuration/healthendpoints REST endpoint to initialize the configuration.
-
Using a text editor, create an empty text file.
-
Copy and paste an example configuration for health 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, refer to the Health endpoint parameters section.
-
Save the file as a json file. For example, as ConfigureHealthEndpoints.json.
-
Open a command line session. Change directory to the location of the saved file from the previous step.
-
Enter the following cURL command (which uses the PUT method) to initialize the health endpoint configuration.
curl -i -k -u <username>:<password> -d "@<json file name>.json" -H "Content-Type: application/json" -X PUT "https://<host>:<port>/api/v1/configuration/healthendpoints"
For additional information on the curl parameters, such as -i or -k, refer to the Configuration tools section.
Note: For a list of other REST operations you can perform, like updating or replacing a health endpoints configuration, see Health endpoints.
Health endpoint parameters
The following parameters are available for configuring health endpoints:
|
Parameter |
Required |
Type |
Description |
|---|---|---|---|
|
id |
Optional for POST, required for PUT |
string |
Uniquely identifies the endpoint. This can be any alphanumeric string. If left blank, a unique value is generated automatically. Allowed value: any string identifier |
|
endpoint |
Required |
string |
The URL of the OMF endpoint to receive this health data. Allowed value: well-formed http or https endpoint string Default: null |
|
username |
Optional for PI Web API endpoints |
string |
The username used to authenticate with a PI Web API OMF endpoint. PI server: Allowed value: any string Default: null Note: The property pair Username/Password is only for basic authentication with PI Web API. The pair ClientId/ClientSecret is only for authentication with CONNECT data services. For PI Web API, if Username/Password are omitted, then Kerberos/NTLM is used instead. |
|
password |
Required for PI Web API endpoints |
string |
The password used to authenticate with a PI Web API OMF endpoint. PI server: Allowed value: any string Default: null |
|
clientId |
Required for CONNECT data services endpoints |
string |
The client ID used for authentication with an CONNECT data services OMF endpoint. Allowed value: any string Default: null |
|
clientSecret |
Required for CONNECT data services endpoints |
string |
The client secret used for authentication with an CONNECT data services OMF endpoint. Allowed value: any string Default: null |
|
tokenEndpoint |
Optional for CONNECT data services endpoints |
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 security certificate. Use for testing only with self-signed certificates; AVEVA recommends keeping this set to the default, true, in production environments. Allowed value: true or false Default value: true |
Examples
CONNECT data services endpoint
{
"id": "CONNECT data services",
"endpoint": "https://<CONNECT data services OMF endpoint>",
"clientId": "<clientid>",
"clientSecret": "<clientsecret>"
}
PI Web API endpoint
{
"id": "PI Web API",
"endpoint": "https://<pi web api server>:<port>/piwebapi/omf/",
"username": "<username>",
"password": "<password>"
}
REST URLs
|
Relative URL |
HTTP verb |
Action |
|---|---|---|
|
api/v1/configuration/healthEndpoints |
GET |
Gets all configured health endpoints |
|
api/v1/configuration/healthEndpoints |
DELETE |
Deletes all configured health endpoints |
|
api/v1/configuration/healthEndpoints |
POST |
Adds an array of health endpoints or a single endpoint. Fails if any endpoint already exists |
|
api/v1/configuration/healthEndpoints |
PUT |
Replaces all health endpoints. Note: Requires an array of endpoints |
|
api/v1/configuration/healthEndpoints/Id |
GET |
Gets configured health endpoint by Id |
|
api/v1/configuration/healthEndpoints/Id |
DELETE |
Deletes configured health endpoint by Id |
|
api/v1/configuration/healthEndpoints/Id |
PUT |
Updates health endpoint with the specified Id |
Note: Replace Id with the ID of the health endpoint.