Event Management Client for Java¶
Introduction¶
The Event Management Java client allows you to manage events associated with assets and event types. Refer to Event Management for more information about the service.
Further implementation of the Event Management SDK library has been shown in a sample project that you can download and test in local or on Insights Hub application. Please refer to this repository: industrial-iot-java-sdk-examples
Hint
Placeholders in the following samples are indicated by angular brackets < >
.
Event Type Operations¶
The Event Types client creates, reads, updates and deletes event types.
Client name: EventTypesClient
List all Event Types¶
// Construct EventTypesClient object
EventTypesClient eventTypesClient = EventTypesClient.builder()
.mindsphereCredentials(<credentials>)
.restClientConfig(<config>)
.build();
EventType event_types = null;
try {
event_types = eventTypeClient.getEventTypes(<page>, <size>, "<sort>", "<filter>", "<ifNoneMatch>");
} catch (MindsphereException e) {
// Exception Handling
}
Create an Event Type¶
Custom event type IDs must be prefixed with the tenant name followed by a dot.
// Construct the EventTypesClient object as shown above
// Define the event type to be created
String event_type_name = "<event_type_name>";
EventType event_type = new EventType();
event_type.setName(event_type_name);
event_type.setTtl(<ttl>);
event_type.setScope(EventType.ScopeEnum.LOCAL);
// Define fields for the event type
Field field = new Field();
field.setName("<field_name>");
field.setFilterable(Boolean.TRUE);
field.required(Boolean.TRUE);
field.setType(Field.TypeEnum.INTEGER);
// Add the fields to the event type
List<Field> field_list = new ArrayList<>();
field_list.add(field);
event_type.setFields(field_list);
EventType created_event_type = null;
try {
created_event_type = event_type_client.createEventType(event_type);
} catch (MindsphereException e) {
// Exception handling
}
Update an Event Type¶
Update the Scope of an Event Type¶
// Construct EventTypesClient object as shown above
// Define the event type patch to update the event type with
EventTypePatch event_type_patch = new EventTypePatch();
event_type_patch.setOp(EventTypePatch.OperationEnum.REPLACE);
event_type_patch.setPath("/scope");
event_type_patch.setValue(ScopeEnum.GLOBAL.getValue());
EventType updated_event_type = null;
try {
updated_event_type = event_type_client.updateEventType("<event_type_id>", "<etag>", event_type_patch);
} catch (MindsphereException e) {
// Exception Handling
}
Add a Field to an Event Type¶
// Construct EventTypesClient object as shown above
// Create the field to be added
Field new_field = new Field();
new_field.setName("<field_name>");
new_field.setUpdatable(Boolean.FALSE);
new_field.setType(Field.TypeEnum.STRING);
// Define the event type patch to update the event type with
EventTypePatch event_type_patch = new EventTypePatch();
event_type_patch.setOp(EventTypePatch.OperationEnum.ADD);
event_type_patch.setPath(EventManagementConstants.ADD_NEW_FIELD);
ObjectMapper object_mapper = new ObjectMapper();
String field_as_string = object_mapper.writeValueAsString(field)
event_type_patch.setValue(field_as_string);
EventType updated_event_type = null;
try {
updated_event_type = event_type_client.updateEventType("<event_type_id>", "<etag>", event_type_patch);
} catch (MindsphereException e) {
// Exception Handling
}
Alternatively, use the addNewFieldToEventType
method.
//Construct EventTypesClient object as shown above
// Create the field to be added
Field new_field = new Field();
new_field.setName("<field_name>");
new_field.setUpdatable(Boolean.FALSE);
new_field.setType(Field.TypeEnum.STRING);
EventType updated_event_type = null;
try {
updated_event_type = event_type_client.addNewFieldToEventType(eventType.getId(), "<etag>", new_field);
} catch (MindsphereException e) {
// Exception Handling
}
Make a Field of an Event Type Mandatory¶
// Construct EventTypesClient object as shown above
// Define the event type patch to update the event type with
EventTypePatch patch = new EventTypePatch();
patch.setOp(EventTypePatch.OperationEnum.REPLACE);
patch.setPath("/fields/<fieldName>/required");
patch.setValue(Boolean.FALSE);
EventType updatedEventType = null;
try {
updatedEventType = event_type_client.updateEventType("<event_type_id>", "<etag>", eventTypePatch);
} catch (MindsphereException e) {
// Exception Handling
}
Read an Event Type by ID¶
//Construct EventTypesClient object as shown above
EventType event_type = null;
try {
event_type = event_type_client.getEventTypesById("<event_type_id>", "<ifNoneMatch>");
} catch (MindsphereException e) {
// Exception Handling
}
Delete an Event Type by ID¶
// Construct the EventTypesClient object as shown above
try {
event_type_client.deleteEventType("<event_type_id>", "<ifMatch>");
} catch (MindsphereException ex) {
// Exception Handling
}
Event Operations¶
The Events client creates, reads and updates standard and custom events.
Client name: EventsClient
List all Events¶
Note
By default, the response is paginated with 20 elements per page.
Attention
The getEvents
method returns a paginated list of BaseEvent
objects. These objects must be typecasted to be used as MindsphereStandardEvent
or CustomEvent
as shown below.
List all Standard Events¶
// Construct the EventsClient object
EventsClient eventClient = EventsClient.builder()
.mindsphereCredentials(<credentials>)
.restClientConfig(<config>)
.build();
Events events = null;
try {
events = eventClient.getEvents(<size>, <page>, "<filter>", "<sort>", "<ifNoneMatch>", history);
if (events != null && events.getEmbedded() != null
&& events.getEmbedded().getEvents() != null && !events.getEmbedded().getEvents().isEmpty())
{
List<BaseEvent> eventList = events.getEmbedded().getEvents();
// Typecast the list object to obtain a MindsphereStandardEvent object
MindsphereStandardEvent standard_event = eventList.get(0);
}
} catch (MindsphereException ex) {
// Exception Handling
}
List all Events of a Specific Event Type¶
For obtaining events of specific (custom) event type, a filter for the respective event type ID must be defined, e.g. for event type ID e5e6460e-60da-4cc9-b4b7-a7af3cc9fca6
:
String filter = "{\"typeId\":\"e5e6460e-60da-4cc9-b4b7-a7af3cc9fca6\"}";
Sample implementation:
// Construct the EventsClient object as shown above
Events events = null;
try {
String filter = "{\"type_id\":\"<event_type_id>\"}";
events = eventClient.getEvents(<size>, <page>, filter, "<sort>", "<ifNoneMatch>", history);
if (events != null && events.getEmbedded() != null
&& events.getEmbedded().getEvents() != null && !events.getEmbedded().getEvents().isEmpty())
{
List<BaseEvent> eventList = events.getEmbedded().getEvents();
CustomEvent custom_event = (CustomEvent)eventList.get(0);
}
} catch (MindsphereException ex) {
// Exception Handling
}
Create a Standard Event¶
// Construct the EventsClient object as shown above
// Construct the MindSphereStandardEvent object to be created
MindSphereStandardEvent standard_event = new MindSphereStandardEventt();
// Set the base properties
standard_event.setCorrelationId("<correlation_id>");
standard_event.setEntityId("<entity_id>");
standard_event.setTimestamp("<timestamp>");
// Set the standard event properties
standard_event.setDescription("<description>");
standard_event.setSeverity(<severity>);
standard_event.setCode("<code>");
standard_event.setAcknowledged(<acknowledged>);
MindSphereStandardEvent created_standard_event = null;
try {
created_standard_event = eventClient.createStandardEvent(standard_event);
} catch (MindsphereException ex) {
// Exception Handling
}
Alternatively, provide the standard event in JSON format.
String standard_event_as_json = "{" +
"\"correlationId\":\"<correlation_id>\"," +
"\"timestamp\":\"<timestamp\"," +
"\"entityId\":\"<entity_id>\"," +
"\"severity\":<severity>," +
"\"description\":\"<description>\"," +
"\"code":\"<code>\"," +
"\"source\":\"source\"," +
"\"acknowledged\":\"<acknowledged>" +
"}";
MindSphereStandardEvent created_standard_event = null;
try {
created_standard_event = (MindSphereStandardEvent) eventClient.createEvent(standard_event_as_json);
} catch (MindsphereException ex) {
// Exception Handling
}
Create a Custom Event¶
Custom events are instantiated from a user-defined event type.
// Construct the EventsClient object as shown above
// Construct the CustomEvent object to be created
CustomEvent custom_event = new CustomEvent();
// Set the base properties
custom_event.setCorrelationId("<correlation_id>");
custom_event.setEntityId("<entity_id>");
custom_event.setTimestamp("<timestamp>");
custom_event.setTypeId("<event_type_id>");
// Set values for custom fields as hash maps using a key and value pair
custom_event.getFields().put("<custom_field_1>", "<custom_field_value1>");
custom_event.getFields().put("<custom_field_2>", "<custom_field_value2>");
CustomEvent created_custom_event = null;
try {
created_custom_event = eventClient.createCustomEvent(custom_event);
} catch (MindsphereException ex) {
// Exception Handling
}
Alternatively, provide the custom event as in JSON format.
String custom_event_as_json = "{" +
"\"typeId\":\"<event_type_id>\"," +
"\"correlationId\":\"<correlation_id>\"," +
"\"timestamp\":\"<timestamp>\"," +
"\"entityId\":\"<entity_id>\"," +
"\"<custom_field_1>\":\"custom_field_value1\"," +
"\"<custom_field_2>\":\"custom_field_value2\"," +
"}";
CustomEvent created_custom_event = null;
try {
created_custom_event = (CustomEvent)eventClient.createEvent(custom_event_as_json);
} catch (MindsphereException ex) {
// Exception Handling
}
Get an Event by ID¶
// Construct the EventsClient object as shown above
BaseEvent event = null;
try {
event = eventClient.getEventById("<event_id>");
// Check the type of the retrieved event
if (event != null && event instanceof MindsphereStandardEvent) {
// Process the retrieved standard event
MindsphereStandardEvent standard_event = (MindsphereStandardEvent) event;
} else if (event != null && event instanceof CustomEvent) {
// Process the retrieved custom event
CustomEvent custom_event = (CustomEvent) event;
}
} catch (MindsphereException ex) {
// Exception Handling
}
Update an Event¶
Updates the event with the specified ID.
// Construct the EventsClient object as shown above
BaseEvent event = null;
try {
event = eventClient.updateEvents("<event_id>", "<event_json_string>", "<ifMatch>");
// Check the type of the retrieved event as shown above for further processing
} catch (MindsphereException ex) {
// Exception Handling
}
Update a Standard Event¶
Updates the standard event with the specified ID.
// Construct the EventsClient object as shown above
MindSphereStandardEvent updated_standard_event = null;
try {
updated_standard_event = eventClient.updateStandardEvent("<event_id>", "<standard_event>", "<ifMatch>");
} catch (MindsphereException ex) {
// Exception Handling
}
Update a Custom Event¶
Updates the custom event with the specified ID.
// Construct the EventsClient object as shown above
CustomEvent custom_event = null;
try {
custom_event = eventClient.updateCustomEvent("<event_id>", "<customEvent>", "<ifMatch>");
} catch (MindsphereException ex) {
// Exception Handling
}
Event Job Operations¶
The Jobs client creates and retrieves jobs for creating or deleting events.
Client name: JobsClient
Create a Job to Create Events¶
Create a Job to Create Custom Events¶
// Construct a JobsClient object
JobsClient jobs_client = JobsClient.builder()
.restClientConfig(<config>)
.build();
CustomEvent custom_event = new CustomEvent();
custom_event.setTypeId(eventTypeId1);
CustomEvent custom_event2 = new CustomEvent();
custom_event2.setTypeId(eventTypeId2);
List<BaseEvent> event_list = new ArrayList<>();
event_list.add(custom_event);
event_list.add(custom_event2);
CreateEventsJob create_events_job = new CreateEventsJob();
create_events_job.setEvents(event_list);
JobResource job_resource = null;
try {
job_resource = jobs_client.createCreateEventsJob(create_events_job);
} catch (MindsphereException e) {
// Exception handling
}
Create a Job to Create Standard Events¶
MindSphereStandardEvent standard_event = new MindSphereStandardEvent();
MindSphereStandardEvent standard_event2 = new MindSphereStandardEvent();
List<BaseEvent> eventList = new ArrayList<>();
eventList.add(standard_event);
eventList.add(standard_event2);
CreateEventsJob create_events_job = new CreateEventsJob();
create_events_job.setEvents(eventList);
JobResource job_resource = null;
try {
job_resource = jobs_client.createCreateEventsJob(create_events_job);
} catch (MindsphereException e) {
// Exception handling
}
Get a Job to Create Events by its ID¶
//Construct JobsClient object as shown above
String job_id = "<createEventsJobId>";
CreateJobResource create_job_resource = null;
try {
create_job_resource = jobs_client.getCreateEventsJobById(job_id);
} catch (MindsphereException e) {
// Exception handling
}
Create a Job to Delete Events¶
Create a job to delete events which satisfy query parameters. The query parameters are listed in the filter method of the DeleteEventsJob class.
// Create a map of events to be deleted
HashMap<String, String> filter = new HashMap<>();
filter.put("typeId", "com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent");
// Create the DeleteEventsJob instance
DeleteEventsJob delete_events_job = new DeleteEventsJob();
delete_events_job.setFilter(filter);
JobResource job_event = null;
try {
job_event = jobs_client.createDeleteEventsJob(delete_events_job);
} catch (MindsphereException e) {
// Exception handling
}
Get a Job to Delete Events by its ID¶
//Construct JobsClient object as shown above
String job_id = "<delete_events_job_id>";
DeleteJobResource delete_job_resource = null;
try {
delete_job_resource = jobs_client.getDeleteEventsJobById(job_id);
} catch (MindsphereException e) {
// Exception handling
}
Except where otherwise noted, content on this site is licensed under the Development License Agreement.