swagger: '2.0'
info:
title: Event Analytics API
description: Provides the essential functionality for a data-driven analysis of the event data.
version: '3.1.1'
x-released: yes
x-visibility: external
schemes:
- https
basePath: /api/eventanalytics/v3
tags:
- name: Event operations
description: Provides the essential functionality for a data-driven analysis of the event data.
- name: Pattern operations
description: Provides functionality for discovering patterns in a list of events
securityDefinitions:
eventanalytics:
type: oauth2
flow: accessCode
authorizationUrl: 'https://oauth.simple.api/authorization'
tokenUrl: 'https://oauth.simple.api/token'
scopes:
as.ea.u: Use Event analytics functionalities
paths:
/findTopEvents:
post:
tags:
- Event operations
summary: Find most frequent top N events
description: Finds the most frequent events, which are sorted by the number of appearances in a dataset in a descending order.
operationId: topEvents
security:
- eventanalytics:
- as.ea.u
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/TopEventsBody'
responses:
'200':
$ref: "#/responses/200"
'400':
$ref: "#/responses/400-wrong-param"
'403':
$ref: "#/responses/403"
'503':
$ref: "#/responses/503"
/filterEvents:
post:
tags:
- Event operations
summary: Simplifies the dataset to the most meaningful data
description: Filtering the dataset based on the text of the event
operationId: filterEvents
security:
- eventanalytics:
- as.ea.u
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/EventSearchBody'
responses:
'200':
$ref: "#/responses/200-eventsList"
'400':
$ref: "#/responses/400-wrong-param"
'403':
$ref: "#/responses/403"
'503':
$ref: "#/responses/503"
/countEvents:
post:
tags:
- Event operations
summary: Determines the number of events for a required time resolution.
description: The microservice takes as an input the entire dataset and the time resolution (example 100ms). The micro service will output the given time interval (startTime, endTime) and the resulted number of event occurrences.
operationId: countEvents
security:
- eventanalytics:
- as.ea.u
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/EventCountBody'
responses:
'200':
$ref: "#/responses/200-eventCount"
'400':
$ref: "#/responses/400-wrong-param"
'403':
$ref: "#/responses/403"
'503':
$ref: "#/responses/503"
/removeDuplicateEvents:
post:
tags:
- Event operations
summary: Removes the duplicate events
description: Determine pre-existing relationships between events for a requested temporal resolution (example 500ms) and reduce the data set by aggregating events with duplicate value.
operationId: removeDuplicateEvents
security:
- eventanalytics:
- as.ea.u
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/DuplicateEventsRemovalBody'
responses:
'200':
$ref: "#/responses/200-duplicate"
'400':
$ref: "#/responses/400-wrong-param"
'403':
$ref: "#/responses/403"
'503':
$ref: "#/responses/503"
/matchEventPatterns:
post:
tags:
- Pattern operations
summary: Applies the patterns specified in body on a list of events
description: Finds all instances of the specified pattern(s) in a collection of events.
operationId: matchPatternsOverEvents
security:
- eventanalytics:
- as.ea.u
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/PatternMatchingBody'
responses:
'200':
$ref: "#/responses/200-patternMatching"
'400':
$ref: "#/responses/400-wrong-param"
'403':
$ref: "#/responses/403"
'503':
$ref: "#/responses/503"
parameters:
TopEventsBody:
name: data
in: body
required: true
description: >-
Data structure with three parts - numberOfTopPositionsRequired, eventsMetadata, and events.
- numberOfTopPositionsRequired How many top positions will be returned in the response. Has to be a positive integer. If not specified, the default value 10 will be used.
- eventsMetadata Metadata for the events list specifying the property name of the item in the events list that contains the text of the event.
- events List with the events that will be processed.
schema:
$ref: '#/definitions/TopEventsInputDataModel'
PatternBody:
name: data
in: body
required: true
description: >-
Pattern to be added.
schema:
$ref: '#/definitions/MatchingPattern'
PatternDefinitionBody:
name: data
in: body
required: true
description: >-
Pattern body.
schema:
$ref: '#/definitions/PatternDefinition'
PatternMatchingBody:
name: data
in: body
required: true
description: >-
Data structure with four parts - maxPatternInterval, patternsList, nonEvents and eventsInput.
- maxPatternInterval The maximum time length (in milliseconds) of the sliding window where the pattern occurs (Maximum difference allowed between the first event of the pattern and the last one).
- patternsList The patterns to be found in events. The eventText can contain regular expressions. The acceptable syntax for the regular expressions is the java syntax.
minRepetitions and maxRepetitions represent the minimum and maximum number of events of the specified type that are allowed to occur in order for the pattern to be matched on the events.
- nonEvents A list of events that is not allowed to be part of a pattern. Any pattern which contains a non-event is excluded from the final report.
- eventsInput Metadata for the events list specifying the property name of the item in the events list that contains the text of the event and the list with the events that will be processed.
schema:
$ref: '#/definitions/PatternMatchingInputDataModel'
EventSearchBody:
name: data
in: body
required: true
description: >-
Data structure with three parts - eventsMetadata, filterList, and events.
- eventsMetadata Metadata for the events list specifying the property name of the item in the events list that contains the text of the event.
- filterList Types of events to be removed
- events List with the events that will be processed.
schema:
$ref: '#/definitions/EventSearchInputDataModel'
EventCountBody:
name: data
in: body
required: true
description: >-
Data structure with two parts eventsMetadata, events.
- eventsMetadata Metadata for the events list specifying the property name of the item in the events list that contains the text of the event (eventTextPropertyName) and time window length in miliseconds of the period in which time interval will be split (splitInterval).
- events List with the events that will be processed.
schema:
$ref: '#/definitions/EventInput'
DuplicateEventsRemovalBody:
name: data
in: body
required: true
description: >-
Data structure with two parts eventsMetadata, events.
- eventsMetadata Metadata for the events list specifying the property name of the item in the events list that contains the text of the event (eventTextPropertyName) and time window length in miliseconds of the period in which time interval will be split (splitInterval).
- events List with the events that will be processed.
schema:
$ref: '#/definitions/EventInput'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/TopEventOutput'
'200-eventsList':
description: OK
schema:
$ref: '#/definitions/EventArrayOutput'
'200-duplicate':
description: OK
schema:
$ref: '#/definitions/DuplicateEventArrayOutput'
'200-eventCount':
description: OK
schema:
$ref: '#/definitions/EventCountOutput'
'200-patternMatching':
description: OK
schema:
$ref: '#/definitions/PatternMatchingOutput'
'400-wrong-param':
description: Wrong parameters
schema:
$ref: '#/definitions/VndError'
'403':
description: 'Not Authorized. Missing security scope \"as.ea.u\"'
schema:
$ref: '#/definitions/VndError'
'503':
description: >-
Internal error
schema:
$ref: '#/definitions/VndError'
definitions:
TopEventsInputDataModel:
description: Data model describing the input for the findTopEvents functionality
allOf:
- $ref: '#/definitions/EventsInputModel'
- type: object
properties:
numberOfTopPositionsRequired:
type: integer
format: int32
minimum: 1
default: 10
description: >-
How many top positions will be returned in the response. Has to be a positive integer.
If not specified, the default value 10 will be used.
example:
numberOfTopPositionsRequired: 5
eventsMetadata:
eventTextPropertyName: 'text'
events:
- _time: '2017-10-01T12:00:00.001Z'
text: 'INTRODUCING FUEL'
text_qc: 0
- _time: '2017-10-01T12:00:01.001Z'
text: 'Status@Flame On'
text_qc: 0
- _time: '2017-10-01T12:00:02.001Z'
text: 'Status@Flame On'
text_qc: 0
required:
- events
TopEventOutput:
type: array
description: 'Tuple containing frequency of event and event text'
items:
type: object
properties:
appearances:
type: integer
format: int64
example: 76
text:
type: string
example: "event text"
example:
- appearances: 2
text: 'Status@Flame On'
- appearances: 1
text: 'INTRODUCING FUEL'
EventSearchInputDataModel:
description: Data model describing the input for the eventsSearch functionality
allOf:
- $ref: '#/definitions/EventsInputModel'
- type: object
properties:
filterList:
type: array
items:
type: string
description: List of events which will be removed from the input list
example: ["START","STOP"]
example:
eventsMetadata:
eventTextPropertyName: 'text'
filterList:
- 'INTRODUCING FUEL'
- 'MEANINGLESS ALARM'
- 'Status@Flame On'
events:
- _time: '2017-10-01T12:00:00.001Z'
text: 'INTRODUCING FUEL'
text_qc: 0
- _time: '2017-10-01T12:00:01.001Z'
text: 'Status@Flame On'
text_qc: 0
- _time: '2017-10-01T12:00:02.001Z'
text: 'Status@Flame Off'
text_qc: 0
- _time: '2017-10-01T12:00:03.001Z'
text: 'Error code: 340'
text_qc: 0
required:
- filterList
- events
- eventsMetadata
Event:
type: object
description: An event object (a tuple of time and text)
properties:
_time:
type: string
format: dateTime
description: 'Timestamp of the event in the ISO 8601'
example: '2017-10-01T12:00:00.001Z'
text:
type: string
description: 'The text of the event'
example: 'event text'
text_qc:
type: integer
format: int32
minimum: 0
maximum: 1
description: "Quality check flag"
required:
- _time
- text
EventsInputModel:
type: object
description: 'Contains the events and the metadata regarding the events structure'
properties:
eventsMetadata:
description: 'Metadata for the events list'
type: object
properties:
eventTextPropertyName:
type: string
description: 'The property name of the events list objects that contains the text of the event'
example: 'text'
events:
type: array
items:
$ref: '#/definitions/Event'
example:
eventsMetadata:
eventTextPropertyName: 'text'
events:
- _time: '2017-10-01T12:00:00.001Z'
text: 'INTRODUCING FUEL'
text_qc: 0
- _time: '2017-10-01T12:00:01.001Z'
text: 'Status@Flame On'
text_qc: 0
- _time: '2017-10-01T12:00:02.001Z'
text: 'Status@Flame Off'
text_qc: 0
- _time: '2017-10-01T12:00:03.001Z'
text: 'Error code: 340'
text_qc: 0
- _time: '2017-10-01T12:00:03.001Z'
text: 'Error code: 340'
text_qc: 0
required:
- events
- eventsMetadata
EventInput:
type: object
description: 'Contains the events and the metadata regarding the events structure'
properties:
eventsMetadata:
description: 'Metadata for the events list'
type: object
properties:
eventTextPropertyName:
type: string
description: 'The property name of the events list objects that contains the text of the event'
example: 'text'
splitInterval:
type: integer
format: int32
description: 'The window length represents the value in milliseconds of the period in which user wants to split input interval'
example: 3
events:
type: array
items:
$ref: '#/definitions/Event'
example:
eventsMetadata:
eventTextPropertyName: 'text'
splitInterval: 5000
events:
- _time: '2017-10-01T12:00:00.001Z'
text: 'INTRODUCING FUEL'
text_qc: 0
- _time: '2017-10-01T12:00:01.001Z'
text: 'Status@Flame On'
text_qc: 0
- _time: '2017-10-01T12:00:02.001Z'
text: 'Status@Flame Off'
text_qc: 0
- _time: '2017-10-01T12:00:03.001Z'
text: 'Error code: 340'
text_qc: 0
- _time: '2017-10-01T12:00:04.001Z'
text: 'Error code: 340'
text_qc: 0
- _time: '2017-10-01T12:00:06.001Z'
text: 'INTRODUCING FUEL'
text_qc: 0
- _time: '2017-10-01T12:00:08.001Z'
text: 'Status@Flame On'
text_qc: 0
- _time: '2017-10-01T12:00:09.001Z'
text: 'Status@Flame Off'
text_qc: 0
required:
- events
- eventsMetadata
EventCountOutput:
type: object
description: 'Model containing startTime, endTime and number of events produced between startTime and endTime'
properties:
output:
type: array
items:
$ref: '#/definitions/EventCountOutputItem'
example:
output:
- startTime: '2017-10-01T12:00:00.001Z'
endTime: '2017-10-01T12:00:05Z'
eventCount: 5
- startTime: '2017-10-01T12:00:05.001Z'
endTime: '2017-10-01T12:00:10Z'
eventCount: 3
required:
- output
EventCountOutputItem:
type: object
description: 'Item containing one element from the count output'
properties:
startTime:
type: string
format: dateTime
description: 'Timestamp of the event in the ISO 8601'
example: '2017-10-01T12:00:00.001Z'
endTime:
type: string
format: dateTime
description: 'Timestamp of the event in the ISO 8601'
example: '2017-10-01T12:00:00.001Z'
eventCount:
type: integer
format: int64
example: 76
example:
startTime: '2017-10-01T12:00:00.001Z'
endTime: '2017-10-01T12:00:04.001Z'
eventCount: 5
EventArrayOutput:
type: object
properties:
output:
type: array
items:
$ref: '#/definitions/Event'
example:
output:
- _time: '2017-10-01T12:00:02.001Z'
text: 'Status@Flame Off'
text_qc: 0
- _time: '2017-10-01T12:00:03.001Z'
text: 'Error code: 340'
text_qc: 0
required:
- output
DuplicateEventArrayOutput:
type: object
properties:
output:
type: array
items:
$ref: '#/definitions/Event'
example:
output:
- _time: '2017-10-01T12:00:00.001Z'
text_qc: 0
text: 'INTRODUCING FUEL'
- _time: '2017-10-01T12:00:01.001Z'
text_qc: 0
text: 'Status@Flame On'
- _time: '2017-10-01T12:00:02.001Z'
text_qc: 0
text: 'Status@Flame Off'
- _time: '2017-10-01T12:00:03.001Z'
text_qc: 0
text: 'Error code: 340'
- _time: '2017-10-01T12:00:06.001Z'
text_qc: 0
text: 'INTRODUCING FUEL'
- _time: '2017-10-01T12:00:08.001Z'
text_qc: 0
text: 'Status@Flame On'
- _time: '2017-10-01T12:00:09.001Z'
text_qc: 0
text: 'Status@Flame Off'
required:
- output
PatternMatchingInputDataModel:
description: Data model describing the input for the Pattern Matching functionality
type: object
properties:
maxPatternInterval:
type: integer
format: int32
description: 'The maximum time length (in milliseconds) of the sliding window where the pattern occurs'
example: 100
patternsList:
type: array
items:
$ref: '#/definitions/PatternDefinition'
nonEvents:
type: array
items:
type: string
description: List of events which will be removed from the input list
example: ["Error 2.. occurred","STOPPING ENGINE"]
eventsInput:
$ref: '#/definitions/EventsInputModel'
example:
maxPatternInterval: 200000
patternsList:
- pattern:
- eventText: "INTRODUCING FUEL"
minRepetitions: 1
maxRepetitions: 2
- eventText: "Status@Flame On"
minRepetitions: 0
maxRepetitions: 1
- eventText: "Module STOP due to parameter assignment"
minRepetitions: 1
maxRepetitions: 1
- pattern:
- eventText: "Downloading the module database causes module .. restart"
minRepetitions: 1
maxRepetitions: 1
- eventText: "The SIMATIC mode was selected for time-of-day synchronization of the module with Id: .."
minRepetitions: 1
maxRepetitions: 1
nonEvents:
- "Error 2.. occurred"
- "STOPPING ENGINE"
eventsInput:
eventsMetadata:
eventTextPropertyName: 'text'
events:
- _time: '2017-10-01T12:00:00.001Z'
text: 'Downloading the module database causes module 11 restart'
text_qc: 0
- _time: '2017-10-01T12:00:01.001Z'
text: 'The direction for forwarding the time of day is recognized automatically by the module'
text_qc: 0
- _time: '2017-10-01T12:00:02.001Z'
text: 'Status@Flame On'
text_qc: 0
- _time: '2017-10-01T12:00:03.001Z'
text: 'The SIMATIC mode was selected for time-of-day synchronization of the module with Id: 33'
text_qc: 0
- _time: '2017-10-01T12:00:06.001Z'
text: 'INTRODUCING FUEL'
text_qc: 0
- _time: '2017-10-01T12:00:09.001Z'
text: 'Module STOP due to parameter assignment'
text_qc: 0
PatternMatchingOutput:
description: Data model describing the output for the Pattern Matching functionality
type: object
properties:
output:
type: array
items:
$ref: '#/definitions/PatternFoundByMatching'
example:
output:
- patternIndex: 1
timeWindow:
startTimestamp : '2017-10-01T12:00:00.001Z'
endTimestamp: '2017-10-01T12:00:03.001Z'
matchedEvents:
- _time: '2017-10-01T12:00:00.001Z'
text_qc: 0
text: 'Downloading the module database causes module 11 restart'
- _time: '2017-10-01T12:00:03.001Z'
text_qc: 0
text: 'The SIMATIC mode was selected for time-of-day synchronization of the module with Id: 33'
- patternIndex: 0
timeWindow:
startTimestamp : '2017-10-01T12:00:06.001Z'
endTimestamp: '2017-10-01T12:00:09.001Z'
matchedEvents:
- _time: '2017-10-01T12:00:06.001Z'
text_qc: 0
text: 'INTRODUCING FUEL'
- _time: '2017-10-01T12:00:09.001Z'
text_qc: 0
text: 'Module STOP due to parameter assignment'
PatternFoundByMatching:
description: Data model describing one sequence that matches a pattern
type: object
properties:
patternIndex:
type: integer
description: The index of the pattern based on request object
timeWindow:
type: object
items:
$ref: '#/definitions/TimeWindow'
pattern:
type: array
items:
$ref: '#/definitions/MatchingPattern'
matchedEvents:
type: array
items:
$ref: '#/definitions/Event'
TimeWindow :
type: object
description: The time interval of matched pattern, containing the following information startTimestam, endTimestamp.
properties:
startTimestamp:
type: string
format: dateTime
description: The start timestamp of the matched pattern.
endTimestamp:
type: string
format: dateTime
description: The end timestamp of the matched pattern.
required:
- startTimestamp
- endTimestamp
example:
- startTimestamp: '2017-10-01T12:00:00.001Z'
- endTimestamp: '2017-10-01T12:00:10.001Z'
MatchingPattern:
type: object
description: Object containing an event description and an operator that specifies the number of appearances required for the event
properties:
eventText:
type: string
description: Event identifier.
minRepetitions:
type: integer
default: 1;
description: The minimum number of desired repetitions of the event inside the pattern.
maxRepetitions:
type: integer
default: 1
description: The maximum number of desired repetitions of the event inside the pattern.
required:
- eventText
example:
- eventText: "INTRODUCING FUEL2"
minRepetitions: 1
maxRepetitions: 3
- eventText: "The SIMATIC mode was selected for time-of-day synchronization of the module"
minRepetitions: 0
maxRepetitions: 1
- eventText: "Module STOP due to parameter assignment"
minRepetitions: 1
maxRepetitions: 1
PatternDefinition:
type: object
description: The collection of patterns used for matching into the events list.
properties:
folderId:
type: string
description: The id used to reference the folder where the file with the pattern is stored.
fileId:
type: string
description: The id used to reference the file where the pattern is stored.
patternId:
type: string
description: The id used to reference a specific pattern. It is unique inside this collection.
pattern:
type: array
items:
$ref: '#/definitions/MatchingPattern'
example:
patternId: "78c6801e-c502-4223-98eb-f0ba56ca2023"
pattern:
- eventText: "INTRODUCING FUEL"
minRepetitions: 1
maxRepetitions: 3
- eventText: "The SIMATIC mode was selected for time-of-day synchronization of the module"
minRepetitions: 0
maxRepetitions: 1
- eventText: "Module STOP due to parameter assignment"
minRepetitions: 1
maxRepetitions: 1
VndError:
type: object
properties:
logref:
type: string
message:
type: string