1. Overview
The service contains a collection of RESTful service calls to retrieve and update Alarm information relevant to manufacturing execution.
Descriptions of these functions can be found in the section headers for each collection of relevant resources.
2. Resources
2.1. Alarm-controller
Alarm Controller
2.1.1. Gets all the alarms based on the filters applied
GET /v1/alarms
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
endTime |
End time (incase of timeSelection = 7) in ISO 8601 format (yyyy-MM-dd’T’HH:mm:ss.SSSZ) |
string (date-time) |
|
Query |
includeAcknowledged |
Whether to include acknoledged alarms as well |
boolean |
|
Query |
includeClosed |
Whether to include closed (not empty end date) alarms as well |
boolean |
|
Query |
priorities |
Comma seperated list of priorities to include:Low, Medium or High |
string |
|
Query |
sortColumn |
Property name on which sorting is to be done, supports sorting on only single property |
string |
|
Query |
sortDirection |
Sort Direction, either asc or desc |
string |
|
Query |
startTime |
Start time (incase of timeSelection = 7) in ISO 8601 format (yyyy-MM-dd’T’HH:mm:ss.SSSZ) |
string (date-time) |
|
Query |
timeSelection |
Time selection |
integer (int32) |
|
Query |
unitIds |
Unit Ids (Comma seperated) |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
400 |
Bad Request, See message for details |
|
403 |
Forbidden, Authenticated user not present in PlantApps Database |
2.1.2. Fetches top reasons for the alarm
GET /v1/alarms/topReasons
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
alarmId |
The alarmId for which top reasons are required |
integer (int64) |
|
Query |
reasonType |
Reason tree type to get the specified type of top reasons |
enum (Action, Cause) |
|
Query |
topReasonsCount |
Required number of top reasons |
integer (int64) |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
400 |
Bad Request, See message for details |
|
403 |
Forbidden, Authenticated user not present in PlantApps Database |
|
500 |
Internal Server Error |
2.1.3. Gets the alarm record for the alarm Id provided.
GET /v1/alarms/{alarmId}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
alarmId |
Alarm Id to retireve the Alarm Record |
integer (int64) |
2.1.4. Updates the alarm record for the alarm Id provided.
PUT /v1/alarms/{alarmId}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
alarmId |
Alarm Id of the Alarm Record to update |
integer (int64) |
Query |
acknowledge |
Whether to acknowledge the alarm |
boolean |
Body |
alarmRecordUpdateData |
Alarm Record details to be updated |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
304 |
Not Modified, Request body values same as Data Base |
|
400 |
Invalid data supplied. See message for details. |
|
401 |
Unauthorized |
No Content |
403 |
Forbidden |
|
404 |
Not Found, No Alarm found for this alarm Id |
|
422 |
Unprocessable Entity, Invalid data in the request body |
|
500 |
Internal Server error, See logs for details |
2.2. Alarm-sheet-controller
Alarm Sheet Controller
2.2.1. Gets the alarm sheets configured in PA that is authorized for this user, filtered either by the variableId or unitIds
GET /v1/alarmSheets
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
unitIds |
Unit Ids (Comma seperated) whose alarm sheets are to be retrieved |
string |
Query |
variableId |
Variable Id to retrieve the alarm sheets where this variable is configured |
integer (int64) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
400 |
Bad Request, See message for details |
|
401 |
Unauthorized |
No Content |
403 |
Forbidden, No authorized alarm sheets for user in Plant Apps |
2.3. Variable-controller
Variable Controller
2.3.1. Gets the alarm Variable Details for the provided alarm Id.
GET /v1/sourceVariableDetails
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
alarmId |
Alarm Id to retireve the alarm Variable Details |
integer (int64) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
400 |
Bad Request |
|
401 |
Unauthorized |
No Content |
403 |
Forbidden |
3. Definitions
3.1. AlarmCountInfo
Object to hold various alarm counts
| Name | Description | Schema |
|---|---|---|
acknowledgedAlarmCount |
Number of acknowledged alarms |
integer (int64) |
highPriorityAlarmCount |
Number of high alarms |
integer (int64) |
lowPriorityAlarmCount |
Number of low alarms |
integer (int64) |
mediumPriorityAlarmCount |
Number of medium alarms |
integer (int64) |
nonAcknowledgedAlarmCount |
Number of unacknowledged alarms |
integer (int64) |
totalAlarmCount |
Total number of alarms |
integer (int64) |
3.2. AlarmRecord
Alarm Record Object
| Name | Description | Schema |
|---|---|---|
acknowledged |
Whether this alarm is acknowledged or not |
boolean |
acknowledgedBy |
Name of the user who acknowledged this alarm |
string |
acknowledgedOn |
Time when this alarm was acknowledged on(ISO 8601) |
string (date-time) |
action1 |
The level 1 action taken for on regard to this alarm |
|
action2 |
The level 2 action taken for on regard to this alarm |
|
action3 |
The level 3 action taken for on regard to this alarm |
|
action4 |
The level 4 action taken for on regard to this alarm |
|
actionCommentId |
The comment thread Id for action |
integer (int64) |
actionRequired |
Whether this alarm record requires actions to be selected |
boolean |
actionTreeId |
The reason tree Id which is configured as action tree for this alarms template |
integer (int64) |
alarmDescription |
The description for this alarm |
string |
alarmId |
The unique ID for this Alarm Record |
integer (int64) |
alarmRule |
The title of the Alarm Template this alarm is based on |
string |
alarmType |
The Alarm Type |
|
canAcknowledge |
Whether this alarm record can be acknoledged |
boolean |
canPerform |
Whether this alarm record can be editied to add cause and actions |
boolean |
cause1 |
The level 1 cause why this alarm has been raised |
|
cause2 |
The level 2 cause why this alarm has been raised |
|
cause3 |
The level 3 cause why this alarm has been raised |
|
cause4 |
The level 4 cause why this alarm has been raised |
|
causeCommentId |
The comment thread Id for cause |
integer (int64) |
causeRequired |
Whether this alarm record requires causes to be selected |
boolean |
causeTreeId |
The reason tree Id which is configured as cause tree for this alarms template |
integer (int64) |
duration |
The duration (in seconds) this alarm spans from starting to end |
integer (int64) |
endTime |
The end time(ISO 8601) of this alarm |
string (date-time) |
endValue |
Value of the variable’s test when the Alarm is closed |
object |
eventCount |
Number of event this alarm spans after alarm is triggered and until its ends |
integer (int64) |
eventSubTypeDescription |
The event SubType Description, eg Batch |
string |
links |
< Link > array |
|
priority |
The severity of this alarm |
|
sourceUnit |
The unit where the alarm is raised |
|
sourceVariable |
The variable for which the alarm got raised |
|
sourceVariableDataType |
Data type of the alarm source veriable (ex. Integer, String..) |
|
startTime |
The start time(ISO 8601) of this alarm |
string (date-time) |
startValue |
Value of the variable’s test when the Alarm is opened |
object |
3.3. AlarmRecordDetails
Object to hold List of alarm records and count information of that alarms
| Name | Description | Schema |
|---|---|---|
alarmCountInfo |
Object that holds various count info of the alarm record list |
|
alarmRecords |
List of Alarm Records |
< AlarmRecord > array |
3.4. AlarmRecordUpdateData
Object to hold data for updating the alarm record
| Name | Description | Schema |
|---|---|---|
acknowledge |
Whether this alarm is acknowledged or not |
boolean |
action1 |
The level 1 action taken for on regard to this alarm |
integer (int64) |
action2 |
The level 2 action taken for on regard to this alarm |
integer (int64) |
action3 |
The level 3 action taken for on regard to this alarm |
integer (int64) |
action4 |
The level 4 action taken for on regard to this alarm |
integer (int64) |
cause1 |
The level 1 cause why this alarm has been raised |
integer (int64) |
cause2 |
The level 2 cause why this alarm has been raised |
integer (int64) |
cause3 |
The level 3 cause why this alarm has been raised |
integer (int64) |
cause4 |
The level 4 cause why this alarm has been raised |
integer (int64) |
3.5. AlarmSheetRecord
Object that holds alarm sheet related details
| Name | Description | Schema |
|---|---|---|
sheetId |
The Unique ID for this alarm sheet record |
integer (int64) |
variables |
List of variables under this alarm sheet |
< VariableRecord > array |
3.6. AlarmSheetResponse
| Name | Schema |
|---|---|
content |
< AlarmSheetRecord > array |
links |
< Link > array |
3.7. Error
| Name | Description | Schema |
|---|---|---|
code |
string |
|
details |
Details of this error |
object |
3.8. HttpErrorResponse
Error response object to send to the client
| Name | Description | Schema |
|---|---|---|
error |
Details of the error which returned this response |
|
path |
URL of rest resource which responded with this response |
string |
timestamp |
Time when this error is thrown |
string |
3.9. IdNameValue
Generic object to hold Id value pair
| Name | Description | Schema |
|---|---|---|
id |
ID for thos pair |
integer (int64) |
name |
Name of this pair |
string |
3.11. ReasonDto
| Name | Description | Schema |
|---|---|---|
reasonId |
The unique identifier of the reason |
integer (int64) |
reasonName |
The name of the reason |
string |
3.12. Resource«AlarmRecordDetails»
| Name | Description | Schema |
|---|---|---|
alarmCountInfo |
Object that holds various count info of the alarm record list |
|
alarmRecords |
List of Alarm Records |
< AlarmRecord > array |
links |
< Link > array |
3.13. Resource«AlarmRecord»
| Name | Description | Schema |
|---|---|---|
acknowledged |
Whether this alarm is acknowledged or not |
boolean |
acknowledgedBy |
Name of the user who acknowledged this alarm |
string |
acknowledgedOn |
Time when this alarm was acknowledged on(ISO 8601) |
string (date-time) |
action1 |
The level 1 action taken for on regard to this alarm |
|
action2 |
The level 2 action taken for on regard to this alarm |
|
action3 |
The level 3 action taken for on regard to this alarm |
|
action4 |
The level 4 action taken for on regard to this alarm |
|
actionCommentId |
The comment thread Id for action |
integer (int64) |
actionRequired |
Whether this alarm record requires actions to be selected |
boolean |
actionTreeId |
The reason tree Id which is configured as action tree for this alarms template |
integer (int64) |
alarmDescription |
The description for this alarm |
string |
alarmId |
The unique ID for this Alarm Record |
integer (int64) |
alarmRule |
The title of the Alarm Template this alarm is based on |
string |
alarmType |
The Alarm Type |
|
canAcknowledge |
Whether this alarm record can be acknoledged |
boolean |
canPerform |
Whether this alarm record can be editied to add cause and actions |
boolean |
cause1 |
The level 1 cause why this alarm has been raised |
|
cause2 |
The level 2 cause why this alarm has been raised |
|
cause3 |
The level 3 cause why this alarm has been raised |
|
cause4 |
The level 4 cause why this alarm has been raised |
|
causeCommentId |
The comment thread Id for cause |
integer (int64) |
causeRequired |
Whether this alarm record requires causes to be selected |
boolean |
causeTreeId |
The reason tree Id which is configured as cause tree for this alarms template |
integer (int64) |
duration |
The duration (in seconds) this alarm spans from starting to end |
integer (int64) |
endTime |
The end time(ISO 8601) of this alarm |
string (date-time) |
endValue |
Value of the variable’s test when the Alarm is closed |
object |
eventCount |
Number of event this alarm spans after alarm is triggered and until its ends |
integer (int64) |
eventSubTypeDescription |
The event SubType Description, eg Batch |
string |
links |
< Link > array |
|
priority |
The severity of this alarm |
|
sourceUnit |
The unit where the alarm is raised |
|
sourceVariable |
The variable for which the alarm got raised |
|
sourceVariableDataType |
Data type of the alarm source veriable (ex. Integer, String..) |
|
startTime |
The start time(ISO 8601) of this alarm |
string (date-time) |
startValue |
Value of the variable’s test when the Alarm is opened |
object |
3.14. Resource«VariableDetails»
| Name | Description | Schema |
|---|---|---|
links |
< Link > array |
|
variableDataType |
Data type of the veriable (ex. Integer, String..) |
|
variableEngUnit |
The engineerng unit of the variable (ex. Kg, Lux..) |
string |
variableHistoryEndTime |
Variable History End Time |
string (date-time) |
variableHistoryStartTime |
Variable History Start Time |
string (date-time) |
variableId |
The source variable ID of Alarm Record |
integer (int64) |
variableName |
The Name of the variable on which the alarm is raised |
string |
variableTrigger |
The Id value pair of the trigger of this variable that raised alarm |
3.15. TopNReasonsDto
| Name | Description | Schema |
|---|---|---|
level1 |
The level1 of reason |
|
level2 |
The level2 of reason |
|
level3 |
The level3 of reason |
|
level4 |
The level4 of reason |
3.16. TopNReasonsDtoResponse
| Name | Schema |
|---|---|
content |
< TopNReasonsDto > array |
links |
< Link > array |
3.17. VariableDetails
Alarms source variable information dto object
| Name | Description | Schema |
|---|---|---|
links |
< Link > array |
|
variableDataType |
Data type of the veriable (ex. Integer, String..) |
|
variableEngUnit |
The engineerng unit of the variable (ex. Kg, Lux..) |
string |
variableHistoryEndTime |
Variable History End Time |
string (date-time) |
variableHistoryStartTime |
Variable History Start Time |
string (date-time) |
variableId |
The source variable ID of Alarm Record |
integer (int64) |
variableName |
The Name of the variable on which the alarm is raised |
string |
variableTrigger |
The Id value pair of the trigger of this variable that raised alarm |
4. Security
4.1. oauth
Type : oauth2
Flow : accessCode
Token URL : https://localhost:8443/uaa/oauth/authorize
Token URL : https://localhost:8443/uaa/oauth/token
| Name | Description |
|---|---|
default |
Default oauth2 scope. |