API > Event Submission
The receipt of an event or collection of events is done by HTTP POST requests in a variety of supported media types. All requests containing event data to be submitted should be sent to the /events path hanging off of the root context of the auditing service.
The endpoints served out by this service are secured using Cerner's implementation of the OAuth 1.0a spec via the CernerCare OAuth service.
On any kind of failure streaming auditing information to this resource, it is safe to assume the operation may be retried as all operations are idempotent. If the upload of the data is successful, it is safe to assume the service has received the data, it will not need to be re-uploaded again.
Events submitted must meet the following criteria:
USER, EVENT_KEY, etc.).The following are valid HTTP statuses for this POST request.
If, for any reason, any of the events in your array are rejected, the entirety of the batch will be rejected. Your system does not need to account for partially-successful uploads of events.
The receipt of events can be in any of the following media types:
Requests of this type will specify a Content-Type header of application/x-protobuf.
Data passed in the stream is expected to be the serialized EventList Google protocol buffer as defined in the sentinel-protobuf library:
package com.cerner.sentinel.data.protobuf;
option optimize_for = SPEED;
message Event {
required string event_key = 1; //They key definition for an event
required int64 event_time = 2; //Represents the time the event occurred, represented as milliseconds since midnight, January 1, 1970 UTC.
enum Outcome {
SUCCESS = 0; //Denotes the outcome of an event was successful
FAILURE_MINOR = 1; //Denotes a minor failure, as defined by RFC3881-5.1.4
FAILURE_SERIOUS = 2; //Denotes a serious failure, as defined by RFC3881-5.1.4
FAILURE_MAJOR = 3; //Denotes a major failure, as defined by RFC3881-5.1.4
}
required Outcome outcome = 3; //Refers to the outcome of an audit event
optional string tenant = 4; //The optional tenant attached to an event
optional string user = 5; //The optional user attached to an event
message Attribute {
required string name = 1; //the name of the attribute attached to an event
repeated string value = 2; //the actual value of the attribute
}
repeated Attribute attributes = 6; //Custom attributes associated with an audit event
optional bytes registration_version = 7; //The version of the registration tied to a given instance of an event. Not set for events without registrations
}
message EventList {
repeated Event event = 1;
}
The returned information will be the serialized Upload Google protocol buffer (again as defined in the sentinel-protobuf library) for successful uploads:
package com.cerner.sentinel.data.protobuf;
option optimize_for = SPEED;
message Upload {
required int64 event_count = 1; //The number of audit events received
}
In the event of a failure, the entity returned will match the Error Google protocol buffer as defined by errors.proto in the sentinel-protobuf library:
package com.cerner.sentinel.data.protobuf;
option optimize_for = SPEED;
message Error {
enum Type {
GENERIC = 1; // Error for which no more specific type is available.
BAD_FORMAT = 2; // Indicates that input was delivered in an unrecognized or invalid format.
VALIDATION_FAILED = 3; // Indicates that the input provided was syntactically valid but unacceptable based on the endpoint's contract.
DOWN_FOR_MAINTENANCE = 4; // Indicates that the service received the request but is unable to process it due to ongoing maintenance.
}
required Type type = 1; // The type of error that occurred.
optional string message = 2; // A message further explaining the precise cause of the error.
}
Requests of this type will specify a Content-Type header of application/octet-stream.
Use of this media type may be more efficient than the application/x-protobuf type as the data may be efficiently streamed to the service, rather than having to construct the full EventList protocol buffer object (as defined in the sentinel-protobuf library) including every event being streamed before initiating the upload. Data passed in the octet stream is expected to be in the following form, repeating:
event size - The first 4 big-endian bytes define the size of the following event, in two's complement form. The size must translate into a positive integer, and must not be larger than 2^20 (one megabyte).event - The serialized Event Google protocol buffer as defined by events.proto (described above).The response to this request will mirror the format of the one as described in the Protocol Buffer request type described above.
Requests of this type will specify a Content-Type header of application/json. At the root of the object is an events node containing an array of the events that were audited.
The JSON type can also be used to define the events upload. At a minimum, the following fields must be present on an event:
{
"events": [
{
"event_key":"CHART_ACCESS",
"event_time":12345678,
"outcome":0
}
]
}
The event_time field should be the date and time of the event represented in milliseconds since the Unix epoch.
The possible values (and their corresponding integer representations) for outcome are:
The integer representations are supported for backward compatibility; consumers are encouraged to use the more meaningful and readable textual representations.
Refer to the audit event data model for a the purposes of these fields.
Currently, the previous registration_hash field is supported for passivity, but all new consumers should use registration_version and pre-existing consumers should switch to the newer registration_version field.
A full example of the possible fields in a body of audit events follows:
{
"events":[
{
"event_key":"CHART_ACCESS",
"event_time":12345678,
"outcome":0,
"tenant":"tenantValue",
"user":"userVal",
"attributes":[
{
"name":"attrName",
"value":[
"value"
]
}
]
},
{
"event_key":"2b41cfd0-7aa7-46ce-bddc-0aa3ec9bc434",
"event_time":987654,
"outcome":"FAILURE_MINOR",
"registration_version":"8PHqXnfhAYCz6U5IxUXa7/I2pwI="
}
]
}
When the request is successfully concluded, a JSON response body is returned containing the number of events that were accepted. This should always be equal to the number of events you submitted. For example, a successful upload could look similar to the following:
{
"event_count":23
}
An error, however, may look like:
{
"type":"GENERIC",
"message":"The service was unable to fulfill the requested action"
}