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
}