Endpoint: PUT /v1/point-alarm-threshold/{nodeId}
Calling this endpoint requires that the client user has the POINT_ALARM_STATUS::SET_ALARM_THRESHOLD action for the given nodeId.
Sets the alarm threshold for the given node to the request body. If the given threshold is set successfully a new alarm status is calculated for the threshold.
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 1,
"overall":
{
"unit": "C",
"outerHigh": 80,
"innerHigh": 70,
"innerLow": 40,
"outerLow": 20
}
}
The alarm threshold configuration in Enlight would look like this:
| Status | Value |
|---|---|
| Good | |
| Good high | 80 |
| Alert high | 70 |
| Danger | |
| Alert low | 40 |
| Danger low | 20 |
| Good |
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 2,
"overall":
{
"unit": "mm/s",
"outerHigh": 80,
"innerHigh": 70,
"innerLow": 40,
"outerLow": 20
}
}
The alarm threshold configuration in Enlight would look like this:
| Status | Value |
|---|---|
| Danger | |
| Danger high | 80 |
| Alert high | 70 |
| Good | |
| Alert low | 40 |
| Danger low | 20 |
| Danger |
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 3,
"inspection":
{
"choices":
[
{
"answer": "good",
"instruction": "this will set status to good",
"status": 2
},
{
"answer": "alert",
"instruction": "this will set status to alert",
"status": 3
},
{
"answer": "danger",
"instruction": "this will set status to danger",
"status": 4
}
]
}
}
More information about rate of change thresholds can be found here.
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"rateOfChange":
{
"unit": "gE",
"outerHigh": 20,
"innerHigh": 10,
"innerLow": -10,
"outerLow": -20
}
}
More information about band alarm thresholds can be found here.
{
"nodeId": "00000000-0000-0000-0000-000000000000",
"thresholdType": 0,
"bandAlarms": [
{
"label": "the label",
"maxFrequency":
{
"value": 1.337,
"valueType": 1
},
"minFrequency":
{
"value": 1,
"valueType": 1
},
"overallThreshold":
{
"upperAlert":
{
"value": 1,
"valueType": 1
},
"upperDanger": {
"value": 1.337,
"valueType": 1
}
}
}
]
}
More information about HAL alarm thresholds can be found here.
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"halAlarms": [
{
"label": "Name",
"halAlarmType": "GLOBAL",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"halAlarms": [
{
"label": "12 TEETH SPROCKET",
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"halAlarms": [
{
"label": "bpfo",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
},
{
"label": "bpfi",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
},
{
"label": "ftf",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
},
{
"label": "bsf",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
This endpoint does not return any response body on success.
Errors include a response body as described here.
Endpoint: PATCH /v1/point-alarm-threshold/{nodeId}
Calling this endpoint requires that the client user has the POINT_ALARM_STATUS::SET_ALARM_THRESHOLD action for the given nodeId.
The client must set the request header Content-Type to application/json-patch+json to indicate the format of the request.
Whereas the PUT endpoint expects the full threshold to be passed in any request to update the threshold, this endpoint instead only needs each change that should be performed (on the JSON representation of the threshold).
The format of the request body follows RFC 6902. This specification also contains several examples for how to achieve specific changes.
Each operation contains a path parameter to the element which should be targeted by the operation. The structure of the JSON document to patch can be assumed to follow the same format as returned when retrieving an alarm threshold (using GET, with the exception that nodeId can not be changed.
Given an existing alarm threshold with the following definition.
{
"thresholdType": 2,
"overall":
{
"unit": "mm/s",
"outerHigh": 70,
"innerHigh": 50,
"innerLow": 10,
"outerLow": 5
}
}
If a user wanted to change the outerHigh value to 80 the following request body could be used.
[
{"op": "replace", "path": "/overall/outerHigh", "value": 80}
]
Multiple modifications can be performed in the same request. If the user wanted to change both outerHigh and innerHigh the following request could be used.
[
{"op": "replace", "path": "/overall/outerHigh", "value": 80},
{"op": "replace", "path": "/overall/innerHigh", "value": 70}
]
RFC 6902 requires that all operations are successful for the patch operation to be applied. This means that if any individual operation fails, no partial (successful) changes would be applied. Clients should rely on the response status code to determine whether a failure to apply the changes has happened, and any such error will return a 409 Conflict status code.
The specification defines the test operation, which allows a user to add tests of specific values to the patch. This could be used to guard against accidental changes. E.g. if a user wanted to update the outerHigh value, while guarding against making any changes if the value has been changed from the local copy, the following request body could be used.
[
{"op": "test", "path": "/overall/outerHigh", "value": 70},
{"op": "replace", "path": "/overall/outerHigh", "value": 80}
]
If another user has managed to change the value of outerHigh before the user sends their request, the patch would fail and no changes would be made. The server would respond with status code 409 Conflict, indicating that the user has to refresh their local copy before making any changes.
Endpoint: GET /v1/point-alarm-threshold/{nodeId}
Calling this endpoint requires that the client user has the POINT_ALARM_STATUS::GET_ALARM_THRESHOLD action for the given nodeId.
Errors include a response body as described here.
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 1,
"overall":
{
"unit": "mm/s",
"outerHigh": 1.0,
"innerHigh": 2.0,
"innerLow": 3.0,
"outerLow": 4.0
}
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 2,
"overall":
{
"unit": "mm/s",
"outerHigh": 1.0,
"innerHigh": 2.0,
"innerLow": 3.0,
"outerLow": 4.0
}
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 3,
"inspection":
{
"choices":
[
{
"answer": "good",
"instruction": "this will set status to good",
"status": 2
},
{
"answer": "alert",
"instruction": "this will set status to alert",
"status": 3
},
{
"answer": "danger",
"instruction": "this will set status to danger",
"status": 4
}
]
}
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"rateOfChange":
{
"unit": "gE",
"outerHigh": 20,
"innerHigh": 10,
"innerLow": -10,
"outerLow": -20
}
}
More information about band alarm thresholds can be found here.
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"bandAlarms": [
{
"label": "the label",
"maxFrequency": {
"value": 1.337,
"valueType": 1
},
"minFrequency": {
"value": 1,
"valueType": 1
},
"overallAlarmThreshold": {
"upperAlert": {
"value": 1,
"valueType": 1
},
"upperDanger": {
"value": 1.337,
"valueType": 1
}
}
}
]
}
More information about HAL alarm thresholds can be found here.
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"halAlarms": [
{
"label": "Name",
"halAlarmType": "GLOBAL",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"halAlarms": [
{
"label": "12 TEETH SPROCKET",
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
{
"nodeId": "fdeb828e-65d2-4dba-89eb-f7147828b328",
"thresholdType": 0,
"halAlarms": [
{
"label": "bpfo",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
},
{
"label": "bpfi",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
},
{
"label": "ftf",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
},
{
"label": "bsf",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
Endpoint: POST /v1/point-alarm-threshold-batch
Calling this endpoint requires that the client user has the POINT_ALARM_STATUS::GET_ALARM_THRESHOLD_BATCH action. The user must also have the POINT_ALARM_STATUS::GET_ALARM_THRESHOLD action for each node in the list to get a successful response.
The client must set the request header Content-Type to application/json to indicate the format of the request.
Given a POST request containing a list of node IDs, this endpoint returns a list of alarm thresholds per node ID. The result has the same order of node IDs as the input.
Note: This endpoint only accepts measurement points as input node IDs.
The input is a list of node IDs to get the alarm thresholds for.
{
"nodeIDs": []
}
The output is a list of thresholds where each item in the list is defined as by the Get alarm threshold endpoint.
Errors include a response body as described here.
If a user posts the following body:
{
"nodeIDs": [
"12345678-1234-1234-1234-000000000001",
"12345678-1234-1234-1234-000000000002",
"12345678-1234-1234-1234-000000000003"
]
}
The response might look like this:
{
"thresholds": [
{
"nodeId": "12345678-1234-1234-1234-000000000001",
"thresholdType": 1,
"overall":
{
"unit": "mm/s",
"outerHigh": 1.0,
"innerHigh": 2.0,
"innerLow": 3.0,
"outerLow": 4.0
}
},
{
"nodeId": "12345678-1234-1234-1234-000000000002",
"thresholdType": 2,
"overall":
{
"unit": "mm/s",
"outerHigh": 1.0,
"innerHigh": 2.0,
"innerLow": 3.0,
"outerLow": 4.0
}
},
{
"nodeId": "12345678-1234-1234-1234-000000000003",
"thresholdType": 3,
"inspection":
{
"choices":
[
{
"answer": "good",
"instruction": "this will set status to good",
"status": 2
},
{
"answer": "alert",
"instruction": "this will set status to alert",
"status": 3
},
{
"answer": "danger",
"instruction": "this will set status to danger",
"status": 4
}
]
}
}
]
}