# Events

# GET Retrieve Event Definitions

# /definitions/events

# Description

Retrieves the list of latest (based on version number) event definitions. The result can be filtered by providing the filter parameter. The result can be limited by providing the limit parameter (default is 100). Deleted definitions can be included by setting the includeDeleted parameter to true.

# Parameters

Name	Located in	Description	Required	Schema
limit	query	Limit the number of returned values. Defaults to 100 if not specified	No	LimitClause
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-
filter	query	A boolean expression used to filter the results	No	WhereClause

# Responses

Code	Description	Schema
200	Success	EventDefinitions
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# POST Add a New Event definition

# /definitions/events

# Description

Adds a new event definition. It needs to be either a new eventDefinitionId or the provided version property needs to conform to the semantic versioning rules for definitions. Otherwise the request will be rejected. Note that there is NO update of a definition. If changes need to be made, at least a major version increase is required. Therefore, there is also no PUT operation on this endpoint.

# Payload

{
  "eventDefinitionId": "abb.ability.Unique.Identificator",
  "version": "1.0.0",
  "fields": {
    "kilos": {
      "dataType": "number",
      "unit": "kg"
    },
    "category": {
       ...
       "limitState": {
             "dataType" : "string",
             "enum" : ["low", "high", "none"]

        }
    }
  }
}

On the top level of the definition there are only tree properties allowed:

eventDefinitionId - string - mandatory
version - string - semantic version format - mandatory
fields - object - optional

The fields object may contain variables only - no properties, no default values are allowed. Variables inside the event's fields follow the same approach that the regular type definition variables do.

# Responses

Code	Description	Schema
201	Definition was added to database	EventDefinition
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
409	Conflict - definition with this id already exists
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# GET Retrieve an Event Definition

# /definitions/events/{eventDefinitionId}

# Description

Gets latest (based on its version) event definition based on versions for specific eventDefinitionId. Deleted alarm definition can also be retrieved by this operation, if the includeDeleted flag is set to "true".

# Parameters

Name	Located in	Description	Required	Schema
eventDefinitionId	path	Definition id	Yes	string
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-

# Responses

Code	Description	Schema
200	Success. Retrieve object models by filter criteria.	EventDefinition
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# DELETE Delete an Event Definition

# /definitions/events/{eventDefinitionId}

# Description

Marks the event definition as deleted. No new instances can be created and no new versions added. The event definition will stay in the database though, as this is a soft delete. To delete the entity completely (hard delete), please contact the Operations Team.

# Parameters

Name	Located in	Description	Required	Schema
eventDefinitionId	path	Definition id	Yes	string

# Responses

Code	Description	Schema
204	Event definition was successfully deleted.
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# GET Get Event Definition Versions

# /definitions/events/{eventDefinitionId}/versions

# Description

Retrieves a list of available versions for the given eventDefinitionId. In order to retrieve the versions of a soft-deleted definition the includeDeleted flag has to be set to "true".

# Parameters

Name	Located in	Description	Required	Schema
eventDefinitionId	path	Definition id	Yes	string
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-

# Responses

Code	Description	Schema
200	Success	EventVersions
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# GET Get Event Definition by Version Number

# /definitions/events/{eventDefinitionId}/versions/{version}

# Description

Retrieves a specific event definition identified by eventDefinitionId. Additionally, a version number needs to be supplied which can be partial (e.g., 1 or 1.1) which means that the latest sub version of that version will be returned (e.g., 1.2.5 or 1.1.3). In order to retrieve the specified version of a soft-deleted definition the includeDeleted flag has to be set to "true".

# Parameters

Name	Located in	Description	Required	Schema
eventDefinitionId	path	Definition id	Yes	string
version	path	(Partial) version number	Yes	string
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-

# Responses

Code	Description	Schema
200	Success. Retrieve object models by filter criteria.	EventDefinition
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

← Attributes Functions →