event filters description

@@ -203,6 +203,14 @@ public abstract class BaseController {
 
 
     protected final String EVENT_START_TIME_DESCRIPTION = "Timestamp. Events with creation time before it won't be queried.";
     protected final String EVENT_START_TIME_DESCRIPTION = "Timestamp. Events with creation time before it won't be queried.";
     protected final String EVENT_END_TIME_DESCRIPTION = "Timestamp. Events with creation time after it won't be queried.";
     protected final String EVENT_END_TIME_DESCRIPTION = "Timestamp. Events with creation time after it won't be queried.";
+
+    protected final String EVENT_ERROR_FILTER_OBJ = "{ \"eventType\": \"ERROR\", \"server\": \"ip-172-31-24-152\", \"method\": \"onClusterEventMsg\", \"error\": \"Error Message\" }";
+    protected final String EVENT_LC_EVENT_FILTER_OBJ = "{ \"eventType\": \"LC_EVENT\", \"server\": \"ip-172-31-24-152\", \"event\": \"STARTED\", \"status\": \"Success\", \"error\": \"Error Message\" }";
+    protected final String EVENT_STATS_FILTER_OBJ = "{ \"eventType\": \"STATS\", \"server\": \"ip-172-31-24-152\", \"messagesProcessed\": 10, \"errorsOccurred\": 5 }";
+    protected final String DEBUG_FILTER_OBJ = "\"msgDirectionType\": \"IN\", \"server\": \"ip-172-31-24-152\", \"dataSearch\": \"humidity\", \"metadataSearch\": \"deviceName\", \"entityName\": \"DEVICE\", \"relationType\": \"Success\", \"entityId\": \"de9d54a0-2b7a-11ec-a3cc-23386423d98f\", \"msgType\": \"POST_TELEMETRY_REQUEST\", \"isError\": \"false\", \"error\": \"Error Message\" }";
+    protected final String EVENT_DEBUG_RULE_NODE_FILTER_OBJ = "{ \"eventType\": \"DEBUG_RULE_NODE\"," + DEBUG_FILTER_OBJ;
+    protected final String EVENT_DEBUG_RULE_CHAIN_FILTER_OBJ = "{ \"eventType\": \"DEBUG_RULE_CHAIN\"," + DEBUG_FILTER_OBJ;
+
     protected static final String RELATION_TYPE_PARAM_DESCRIPTION = "A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value.";
     protected static final String RELATION_TYPE_PARAM_DESCRIPTION = "A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value.";
     protected static final String RELATION_TYPE_GROUP_PARAM_DESCRIPTION = "A string value representing relation type group. For example, 'COMMON'";
     protected static final String RELATION_TYPE_GROUP_PARAM_DESCRIPTION = "A string value representing relation type group. For example, 'COMMON'";
 
 

@@ -28,7 +28,7 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.ResponseBody;
 import org.springframework.web.bind.annotation.ResponseBody;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.bind.annotation.RestController;
 import org.thingsboard.server.common.data.Event;
 import org.thingsboard.server.common.data.Event;
-import org.thingsboard.server.common.data.event.EventFilter;
+import org.thingsboard.server.common.data.event.BaseEventFilter;
 import org.thingsboard.server.common.data.exception.ThingsboardException;
 import org.thingsboard.server.common.data.exception.ThingsboardException;
 import org.thingsboard.server.common.data.id.EntityId;
 import org.thingsboard.server.common.data.id.EntityId;
 import org.thingsboard.server.common.data.id.EntityIdFactory;
 import org.thingsboard.server.common.data.id.EntityIdFactory;
@@ -45,6 +45,8 @@ import org.thingsboard.server.service.security.permission.Operation;
 @RequestMapping("/api")
 @RequestMapping("/api")
 public class EventController extends BaseController {
 public class EventController extends BaseController {
 
 
+    private static final String NEW_LINE = "\n\n";
+
     @Autowired
     @Autowired
     private EventService eventService;
     private EventService eventService;
 
 
@@ -135,8 +137,16 @@ public class EventController extends BaseController {
     }
     }
 
 
     @ApiOperation(value = "Get Events by event filter (getEvents)",
     @ApiOperation(value = "Get Events by event filter (getEvents)",
-            notes = "Returns a page of events for specified entity by specifying event filter. " +
-                    PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
+            notes = "Returns a page of events for the chosen entity by specifying the event filter. " +
+                    PAGE_DATA_PARAMETERS + NEW_LINE + "5 different eventFilter objects could be set for different event types. " +
+                    "The eventType field is required. Others are optional. If some of them are set, the filtering will be applied according to them. " +
+                    "See the examples below for all the fields used for each event type filtering. " + NEW_LINE +
+                    EVENT_ERROR_FILTER_OBJ + NEW_LINE +
+                    EVENT_LC_EVENT_FILTER_OBJ + NEW_LINE +
+                    EVENT_STATS_FILTER_OBJ + NEW_LINE +
+                    EVENT_DEBUG_RULE_NODE_FILTER_OBJ + NEW_LINE +
+                    EVENT_DEBUG_RULE_CHAIN_FILTER_OBJ + NEW_LINE,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/events/{entityType}/{entityId}", method = RequestMethod.POST)
     @RequestMapping(value = "/events/{entityType}/{entityId}", method = RequestMethod.POST)
     @ResponseBody
     @ResponseBody
@@ -152,7 +162,7 @@ public class EventController extends BaseController {
             @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
             @RequestParam int page,
             @ApiParam(value = "A JSON value representing the event filter.", required = true)
             @ApiParam(value = "A JSON value representing the event filter.", required = true)
-            @RequestBody EventFilter eventFilter,
+            @RequestBody BaseEventFilter eventFilter,
             @ApiParam(value = EVENT_TEXT_SEARCH_DESCRIPTION)
             @ApiParam(value = EVENT_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
             @RequestParam(required = false) String textSearch,
             @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EVENT_SORT_PROPERTY_ALLOWABLE_VALUES)
             @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EVENT_SORT_PROPERTY_ALLOWABLE_VALUES)

+/**
+ * Copyright © 2016-2021 The Thingsboard Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.thingsboard.server.common.data.event;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+
+@ApiModel
+@Data
+public abstract class BaseEventFilter implements EventFilter {
+
+    @ApiModelProperty(position = 1, value = "String value representing msg direction type (incoming to entity or outcoming from entity)", allowableValues = "IN, OUT")
+    protected String msgDirectionType;
+    @ApiModelProperty(position = 2, value = "String value representing the server name, identifier or ip address where the platform is running", example = "ip-172-31-24-152")
+    protected String server;
+    @ApiModelProperty(position = 3, value = "The case insensitive 'contains' filter based on data (key and value) for the message.", example = "humidity")
+    protected String dataSearch;
+    @ApiModelProperty(position = 4, value = "The case insensitive 'contains' filter based on metadata (key and value) for the message.", example = "deviceName")
+    protected String metadataSearch;
+    @ApiModelProperty(position = 5, value = "String value representing the entity type", allowableValues = "DEVICE")
+    protected String entityName;
+    @ApiModelProperty(position = 6, value = "String value representing the type of message routing", example = "Success")
+    protected String relationType;
+    @ApiModelProperty(position = 7, value = "String value representing the entity id in the event body (originator of the message)", example = "de9d54a0-2b7a-11ec-a3cc-23386423d98f")
+    protected String entityId;
+    @ApiModelProperty(position = 8, value = "String value representing the message type", example = "POST_TELEMETRY_REQUEST")
+    protected String msgType;
+    @ApiModelProperty(position = 9, value = "Boolean value to filter the errors", allowableValues = "false, true")
+    protected boolean isError;
+    @ApiModelProperty(position = 10, value = "The case insensitive 'contains' filter based on error message", example = "not present in the DB")
+    protected String errorStr;
+    @ApiModelProperty(position = 11, value = "String value representing the method name when the error happened", example = "onClusterEventMsg")
+    protected String method;
+    @ApiModelProperty(position = 12, value = "The minimum number of successfully processed messages", example = "25")
+    protected Integer messagesProcessed;
+    @ApiModelProperty(position = 13, value = "The minimum number of errors occurred during messages processing", example = "30")
+    protected Integer errorsOccurred;
+    @ApiModelProperty(position = 14, value = "String value representing the lifecycle event type", example = "STARTED")
+    protected String event;
+    @ApiModelProperty(position = 15, value = "String value representing status of the lifecycle event", allowableValues = "Success, Failure")
+    protected String status;
+
+}

@@ -16,23 +16,10 @@
 package org.thingsboard.server.common.data.event;
 package org.thingsboard.server.common.data.event;
 
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModel;
-import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 import org.thingsboard.server.common.data.StringUtils;
 
 
-@Data
 @ApiModel
 @ApiModel
-public abstract class DebugEvent implements EventFilter {
-
-    private String msgDirectionType;
-    private String server;
-    private String dataSearch;
-    private String metadataSearch;
-    private String entityName;
-    private String relationType;
-    private String entityId;
-    private String msgType;
-    private boolean isError;
-    private String error;
+public abstract class DebugEvent extends BaseEventFilter implements EventFilter {
 
 
     public void setIsError(boolean isError) {
     public void setIsError(boolean isError) {
         this.isError = isError;
         this.isError = isError;
@@ -41,7 +28,7 @@ public abstract class DebugEvent implements EventFilter {
     @Override
     @Override
     public boolean hasFilterForJsonBody() {
     public boolean hasFilterForJsonBody() {
         return !StringUtils.isEmpty(msgDirectionType) || !StringUtils.isEmpty(server) || !StringUtils.isEmpty(dataSearch) || !StringUtils.isEmpty(metadataSearch)
         return !StringUtils.isEmpty(msgDirectionType) || !StringUtils.isEmpty(server) || !StringUtils.isEmpty(dataSearch) || !StringUtils.isEmpty(metadataSearch)
-                || !StringUtils.isEmpty(entityName) || !StringUtils.isEmpty(relationType) || !StringUtils.isEmpty(entityId) || !StringUtils.isEmpty(msgType) || !StringUtils.isEmpty(error) || isError;
+                || !StringUtils.isEmpty(entityName) || !StringUtils.isEmpty(relationType) || !StringUtils.isEmpty(entityId) || !StringUtils.isEmpty(msgType) || !StringUtils.isEmpty(errorStr) || isError;
     }
     }
 
 
 }
 }

@@ -16,15 +16,10 @@
 package org.thingsboard.server.common.data.event;
 package org.thingsboard.server.common.data.event;
 
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModel;
-import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 import org.thingsboard.server.common.data.StringUtils;
 
 
-@Data
 @ApiModel
 @ApiModel
-public class ErrorEventFilter implements EventFilter {
-    private String server;
-    private String method;
-    private String error;
+public class ErrorEventFilter extends BaseEventFilter implements EventFilter {
 
 
     @Override
     @Override
     public EventType getEventType() {
     public EventType getEventType() {
@@ -33,6 +28,6 @@ public class ErrorEventFilter implements EventFilter {
 
 
     @Override
     @Override
     public boolean hasFilterForJsonBody() {
     public boolean hasFilterForJsonBody() {
-        return !StringUtils.isEmpty(server) || !StringUtils.isEmpty(method) || !StringUtils.isEmpty(error);
+        return !StringUtils.isEmpty(server) || !StringUtils.isEmpty(method) || !StringUtils.isEmpty(errorStr);
     }
     }
 }
 }

@@ -15,10 +15,10 @@
  */
  */
 package org.thingsboard.server.common.data.event;
 package org.thingsboard.server.common.data.event;
 
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 
 
 @ApiModel
 @ApiModel
 @JsonTypeInfo(
 @JsonTypeInfo(
@@ -33,7 +33,8 @@ import io.swagger.annotations.ApiModel;
         @JsonSubTypes.Type(value = StatisticsEventFilter.class, name = "STATS")
         @JsonSubTypes.Type(value = StatisticsEventFilter.class, name = "STATS")
 })
 })
 public interface EventFilter {
 public interface EventFilter {
-    @JsonIgnore
+
+    @ApiModelProperty(position = 1, required = true, value = "String value representing the event type", example = "STATS")
     EventType getEventType();
     EventType getEventType();
 
 
     boolean hasFilterForJsonBody();
     boolean hasFilterForJsonBody();

@@ -16,16 +16,10 @@
 package org.thingsboard.server.common.data.event;
 package org.thingsboard.server.common.data.event;
 
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModel;
-import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 import org.thingsboard.server.common.data.StringUtils;
 
 
-@Data
 @ApiModel
 @ApiModel
-public class LifeCycleEventFilter implements EventFilter {
-    private String server;
-    private String event;
-    private String status;
-    private String error;
+public class LifeCycleEventFilter extends BaseEventFilter implements EventFilter {
 
 
     @Override
     @Override
     public EventType getEventType() {
     public EventType getEventType() {
@@ -34,6 +28,6 @@ public class LifeCycleEventFilter implements EventFilter {
 
 
     @Override
     @Override
     public boolean hasFilterForJsonBody() {
     public boolean hasFilterForJsonBody() {
-        return !StringUtils.isEmpty(server) || !StringUtils.isEmpty(event) || !StringUtils.isEmpty(status) || !StringUtils.isEmpty(error);
+        return !StringUtils.isEmpty(server) || !StringUtils.isEmpty(event) || !StringUtils.isEmpty(status) || !StringUtils.isEmpty(errorStr);
     }
     }
 }
 }

@@ -16,15 +16,10 @@
 package org.thingsboard.server.common.data.event;
 package org.thingsboard.server.common.data.event;
 
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModel;
-import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 import org.thingsboard.server.common.data.StringUtils;
 
 
-@Data
 @ApiModel
 @ApiModel
-public class StatisticsEventFilter implements EventFilter {
-    private String server;
-    private Integer messagesProcessed;
-    private Integer errorsOccurred;
+public class StatisticsEventFilter extends BaseEventFilter implements EventFilter {
 
 
     @Override
     @Override
     public EventType getEventType() {
     public EventType getEventType() {

@@ -39,10 +39,6 @@ import org.thingsboard.server.dao.event.EventDao;
 import org.thingsboard.server.dao.model.sql.EventEntity;
 import org.thingsboard.server.dao.model.sql.EventEntity;
 import org.thingsboard.server.dao.sql.JpaAbstractDao;
 import org.thingsboard.server.dao.sql.JpaAbstractDao;
 
 
-import java.sql.Connection;
-import java.sql.PreparedStatement;
-import java.sql.ResultSet;
-import java.sql.SQLException;
 import java.util.List;
 import java.util.List;
 import java.util.Objects;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Optional;
@@ -196,7 +192,7 @@ public class JpaBaseEventDao extends JpaAbstractDao<EventEntity, Event> implemen
                         eventFilter.getEntityId(),
                         eventFilter.getEntityId(),
                         eventFilter.getMsgType(),
                         eventFilter.getMsgType(),
                         eventFilter.isError(),
                         eventFilter.isError(),
-                        eventFilter.getError(),
+                        eventFilter.getErrorStr(),
                         eventFilter.getDataSearch(),
                         eventFilter.getDataSearch(),
                         eventFilter.getMetadataSearch(),
                         eventFilter.getMetadataSearch(),
                         DaoUtil.toPageable(pageLink)));
                         DaoUtil.toPageable(pageLink)));
@@ -212,7 +208,7 @@ public class JpaBaseEventDao extends JpaAbstractDao<EventEntity, Event> implemen
                         notNull(pageLink.getEndTime()),
                         notNull(pageLink.getEndTime()),
                         eventFilter.getServer(),
                         eventFilter.getServer(),
                         eventFilter.getMethod(),
                         eventFilter.getMethod(),
-                        eventFilter.getError(),
+                        eventFilter.getErrorStr(),
                         DaoUtil.toPageable(pageLink))
                         DaoUtil.toPageable(pageLink))
         );
         );
     }
     }
@@ -231,7 +227,7 @@ public class JpaBaseEventDao extends JpaAbstractDao<EventEntity, Event> implemen
                         eventFilter.getEvent(),
                         eventFilter.getEvent(),
                         statusFilterEnabled,
                         statusFilterEnabled,
                         statusFilter,
                         statusFilter,
-                        eventFilter.getError(),
+                        eventFilter.getErrorStr(),
                         DaoUtil.toPageable(pageLink))
                         DaoUtil.toPageable(pageLink))
         );
         );
     }
     }

@@ -91,13 +91,13 @@ export interface BaseFilterEventBody {
 
 
 export interface ErrorFilterEventBody extends BaseFilterEventBody {
 export interface ErrorFilterEventBody extends BaseFilterEventBody {
   method?: string;
   method?: string;
-  error?: string;
+  errorStr?: string;
 }
 }
 
 
 export interface LcFilterEventEventBody extends BaseFilterEventBody {
 export interface LcFilterEventEventBody extends BaseFilterEventBody {
   event?: string;
   event?: string;
   status?: string;
   status?: string;
-  error?: string;
+  errorStr?: string;
 }
 }
 
 
 export interface StatsFilterEventBody extends BaseFilterEventBody {
 export interface StatsFilterEventBody extends BaseFilterEventBody {
@@ -115,7 +115,7 @@ export interface DebugFilterRuleNodeEventBody extends BaseFilterEventBody {
   dataSearch?: string;
   dataSearch?: string;
   metadataSearch?: string;
   metadataSearch?: string;
   isError?: boolean;
   isError?: boolean;
-  error?: string;
+  errorStr?: string;
 }
 }
 
 
 export type FilterEventBody = ErrorFilterEventBody & LcFilterEventEventBody & StatsFilterEventBody & DebugFilterRuleNodeEventBody;
 export type FilterEventBody = ErrorFilterEventBody & LcFilterEventEventBody & StatsFilterEventBody & DebugFilterRuleNodeEventBody;