Event Management Client for Java¶

Introduction¶

The Event Management Java client allows you to create and update events associated with assets. It also manages different types of events created by users. Refer to Event Management for more information about the service.

Event Operations¶

The Event Controller manages standard and custom events. It creates, lists, and updates the events based on the API calls.

Client name: EventClient

Create a New Event¶

Note

Entity IDs are cached with 1 minute retention. When an entity (asset) is created, it might only be visible for Event Management after the cache is refreshed.

// Construct the EventClient object
EventClient eventClient =  EventClient.builder()
                              .mindsphereCredentials(credentials)
                              .restClientConfig(config)
                              .build();

// Json string representing Mindsphere standard event or custom event
String eventJsonString = "{\r\n" +
        "  \"typeId\": \"3cb8c2b1-f72e-43fa-ae39-ee9de14b8f26\",\r\n" +
        "  \"correlationId\": \"3ecc3658-96bb-47ff-93b3-93afd640ee10\",\r\n" +
        "  \"entityId\": \"50fd8ab5-23b3-45f7-aca1-12b0b186707b\",\r\n" +
        "  \"timestamp\": \"2018-01-09T13:40:23.438Z\",\r\n" +
        "  \"customStringField\": \"customValue\",\r\n" +
        "  \"customIntegerField\": 10\r\n" +
        "}"

BaseEvent createdEvent = null;
try {
    createdEvent = eventClient.createEvent(eventJsonString);
} catch (MindsphereException ex) {
    // Exception Handling
}

Create a New Custom Event¶

A custom event is an event, which has been assigned to a user-defined event type.

// Construct the EventClient object as shown above

//Construct the CustomEvent object to be created
CustomEvent customEvent = new CustomEvent();
customEvent.setTypeId(eventTypeId);
customEvent.setEntityId(entityId);
customEvent.setTimestamp(timestamp);

Map<String, Object> fields = new HashMap<>();
fields.put("customField", "customValue");
customEvent.setFields(fields);

CustomEvent createdCustomEvent = null;
try {
    createdCustomEvent = eventClient.createCustomEvent(customEvent);
} catch (MindsphereException ex) {
    // Exception Handling
}

Create a New Standard Event¶

Standard events use a predefined event type with the following additional properties:

description
severity
code
source
acknowledged

// Construct the EventClient object as shown above

//Construct the StandardEvent object to be created
MindsphereStandardEvent standardEvent = new MindsphereStandardEvent();
standardEvent.setDescription(description);
standardEvent.setSeverity(severity);
standardEvent.setCode(code);
standardEvent.setAcknowledged(acknowledged);
standardEvent.setEntityId(entityId);
standardEvent.setTimestamp(timestamp);

MindsphereStandardEvent createdStandardEvent = null;
try {
    createdStandardEvent = eventClient.createStandardEvent(standardEvent);
} catch (MindsphereException ex) {
    // Exception Handling
}

Query Events¶

Returns events based on the query parameters.

Note

The default number of elements that will be returned in a page is 20.

// Construct the EventClient object as shown above

Events events = null;
try {
    events = eventClient.getEvents(size, page, filter, sort, ifNoneMatch, history);
} catch (MindsphereException ex) {
    // Exception Handling
}

Query an Event by ID¶

Returns an event with the specified ID.

// Construct the EventClient object as shown above

BaseEvent event = null;
try {
    event = eventClient.getEventById(eventId);
    // The retrieved event can be checked for type as follows
    if (event != null && event instanceof MindsphereStandardEvent) {
        // Process the retrieved Standard event
    } else if (event != null && event instanceof CustomEvent) {
        // Process the retrieved custom event
    }
} catch (MindsphereException ex) {
    // Exception Handling
}

Update an Event¶

Updates an existing event with the specified ID.

// Construct the EventClient object as shown above

BaseEvent event = null;
try {
    event = eventClient.updateEvents(eventId, eventJsonString, ifMatch);
    // The retrieved event can be checked for type as shown above for further processing
} catch (MindsphereException ex) {
    // Exception Handling
}

Update a Standard Event¶

Updates an existing standard event with the specified ID.

// Construct the EventClient object as shown above

MindsphereStandardEvent updatedStandardEvent = null;
try {
    updatedStandardEvent = eventClient.updateEvents(eventId, standardEvent, ifMatch);
} catch (MindsphereException ex) {
    // Exception Handling
}

Update a Custom Event¶

Updates an existing custom event with the specified ID.

// Construct the EventClient object as shown above

CustomEvent customEvent = null;
try {
    customEvent = eventClient.updateEvents(eventId, customEvent, ifMatch);
} catch (MindsphereException ex) {
    // Exception Handling
}

Event Type Operations¶

Event type operations create, list, and update the event types based on the API calls.

Client name: EventTypeClient

Create a New Event Type¶

Creates a new event type with the specified content.

The Default ID is the generated UUID. If a custom ID is provided, it has to be prefixed with the tenant name followed by a dot.

// Construct the EventTypeClient object
EventTypeClient eventTypeClient =  EventTypeClient.builder()
                                      .mindsphereCredentials(credentials)
                                      .restClientConfig(config)
                                      .build();

// Define the Event Type to be created
String eventTypeName = "OilTemperatureRise";
EventType eventType = new EventType();
eventType.setName(eventTypeName);
eventType.setTtl(10);
eventType.setScope(ScopeEnum.LOCAL);

// Define Field values to be associated with the Event Type
Field field = new Field();
field.setName("temperature");
field.setFilterable(Boolean.TRUE);
field.required(Boolean.TRUE);
field.setType(FieldTypeEnum.INTEGER);

// Associate Field values to the Event Type
List<Field> fieldList = new ArrayList<>();
fieldList.add(field);
eventType.setFields(fieldList);

EventType createdEventType = null;
try {
    createdEventType = eventTypeClient.createEventType(eventType);
} catch (MindsphereException e) {
    // Exception handling
}

Query Event Types¶

Returns event types based on the query parameters.

//Construct EventTypeClient object as shown above

EventTypes eventTypes = null;
try {
    eventTypes = eventTypeClient.getEventTypes(page, size, sort, filter, ifNoneMatch);
} catch (MindsphereException e) {
    // Exception Handling
}

Read an Event Type by ID¶

Returns an event type by ID.

//Construct EventTypeClient object as shown above

EventType eventType = null;
try {
    eventType = eventTypeClient.getEventTypesById(eventTypeId, ifNoneMatch);
} catch (MindsphereException e) {
    // Exception Handling
}

Update an Event Type¶

Update the event type with the specified ID by sending only the content to be changed.

//Construct EventTypeClient object as shown above

//Define the Event Tyoe Patch that will be used to update the event Type
EventTypePatch eventTypePatch = new EventTypePatch();
eventTypePatch.setOperation(OperationEnum.REPLACE);
eventTypePatch.setPath("/scope");
eventTypePatch.setValue(ScopeEnum.GLOBAL.getValue());

EventType updatedEventType = null;
try {
    updatedEventType = eventTypeClient.updateEventType(eventTypeId, eventType.getEtag().toString(), patch);
} catch (MindsphereException e) {
    // Exception Handling
}

Event Job Operations¶

The Event Job Controller can be used to create jobs that delete queried events.

Client name: EventJobClient

Create a Job to Delete Events¶

Create a new job to delete events, which satisfy query parameters. The query parameters for selecting the events to be deleted are mentioned as a filter in the DeleteEventsJobDto instance.

// Construct the EventJobClient object
EventJobClient eventJobClient = EventJobClient.builder()
                                    .mindsphereCredentials(credentials)
                                    .restClientConfig(config)
                                    .build();

//Create a DeleteEventsJobDto instance
DeleteEventsJobDto deleteEventsJobDto = new DeleteEventsJobDto();
deleteEventsJobDto.setFilter("typeId", "eventTypeId");

JobResource jobResource = null;
try {
    jobResource = eventJobClient.createDeleteEventsJob(deleteEventsJobDto);
} catch (MindsphereException e) {
    // Exception handling
}

DeleteEventsJobDto instance can be populated with criteria in the following ways:

Using filter key and value

DeleteEventsJobDto deleteEventsJobDto = new DeleteEventsJobDto();
deleteEventsJobDto.setFilter("typeId", "eventTypeId");
deleteEventsJobDto.setFilter("id", "eventId");

Using a HashMap

DeleteEventsJobDto deleteEventsJobDto = new DeleteEventsJobDto();

HashMap<String, String> filterMap = new HashMap<>();
filterMap.put("typeId", "eventTypeId");
filterMap.put("id", "eventId");

deleteEventsJobDto.setFilter(filterMap);

Using filter a string

DeleteEventsJobDto deleteEventsJobDto = new DeleteEventsJobDto();

String filter = "{\"filter\": {  \"id\":\"eventId\"," +
                    \"typeId\":\"eventTypeId\"\r\n" +
                            " } " +
                "}";

deleteEventsJobDto.setFilter(filter);

Read a Job to Delete Events by ID¶

Returns a job to delete events by ID.

//Construct EventJobClient object as shown above

String jobId = "deleteEventsJobId";
JobResource jobResource = null;
try {
    jobResource = eventJobClient.getDeleteEventsJobById(deleteEventsJobId);
} catch (MindsphereException e) {
    // Exception handling
}