Submitting events via API#

The event collector API is designed to allow integration of 3rd party agents to deliver events into Argus.

The API allows submitting single events or a bulk of events, and will handle events asynchronously.

Notes about collector APIs:#

  • Collector APIs are created for high-capacity, asychronous operation.

  • The receiving endpoint will validate the data and the users permissions to add them, and will reject invalid data and data which the user does not have the permission to add.

  • However, the API will return successful result once the data is enqueued for storage, so the results may not be immediately available. If the backend engine is under pressure, the actual storage and indexing of the data may be delayed.

  • The API does not distinguish between add or update. When storing the events, if the same event ID already exists, the event will be updated with changes from the incoming event.

Note

It is not possible to update a FINALIZED event.

If submitting updates to an existing event which has previously been marked as FINALIZED, the update will be silently ignored.
The submit-API will still return status accepted.

The ID of an event is a separate object in the submission request, with properties:

  • type

  • customerID

  • timestamp

  • UUID

The id of an event can also be written using an Argus event ID string, e.g. AGGR/1570715141521/1/1679fbfc-1792-4992-8428-3cb4df642fa8

Submitting an event#

Submit a new event by calling the single event submission API:

#create a new event with signature MySignature
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
  "signature": "MySignature"
}'

By default, this event will be submitted with the following fields:

  • Time: timestamp, startTimestamp and endTimestamp “now”

  • Customer: Will be set to the current users customer

  • Type: Default event type is aggregated. Use type raw to submit raw events.

  • Severity: low

  • Count: 1

  • Properties: agent.id, agent.timestamp and engine.timestamp

Remaining fields have default value null (not set).

To submit an event for a specific customer, you need to populate the id object of the event:

    #create a new event with signature MySignature, for customer "shortname", with a specific event timestamp.
    curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
      "id":{
        "customer": "shortname",
        "timestamp": "2019-10-05T15:07:10Z"
      },
      "signature": "MySignature"
    }'

The endpoint will reject the event if the user does not have access to submit events for the specified customer.

Submission response#

The endpoint will respond with code 201, with a status object containing the generated ID of the accepted event. If the event contained invalid fields, the endpoint will return 412.

Each of the identifying fields (timestamp, customerID, type and UUID) will be given a default value if not specified in the request.

{
 "responseCode":201,
 ...,
 "data":{
   "id":"AGGR/1570715141521/1/1679fbfc-1792-4992-8428-3cb4df642fa8",
   "status":"accepted",
   "message":null
 }
}

Submitting an update#

Submitting an update on a previous event requires the type, timestamp, customer and UUID to be the same as the existing event.

#update the previous event with an updated count
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
  "id": {
    "customer": "shortname",
    "timestamp": "2019-10-05T15:07:10Z",
    "uuid": "1679fbfc-1792-4992-8428-3cb4df642fa8" #type "aggregated" is implicit
  },
  "count": 2
}'

For simplicity, you can use the id field to submit the exact ID string returned in the submission status, which is a general Argus event ID:

#update the previous event with an updated count
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
  "id": "AGGR/1570715141521/1/1679fbfc-1792-4992-8428-3cb4df642fa8",
  "count": 2
}'

Submitting with properties#

Events can contain an arbitrary number of properties, and each property can have a list of values.

Warning

The V1 event search/get API does currently not support multiple values on properties, so an event with multiple property values will be returned as a comma-separated property string

Properties are accumulated on update, so updating an event with new properties will cause the event to contain the accumulated set of properties from all updates/submissions.
Updating an existing property will overwrite the existing value.

The properties are submitted as a map of property keys, each key mapping to a list of values.
For simplicity, sending a single value instead of a list is also supported.

#submit an event with properties
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
  "properties": {
    "myprop": ["val1", "val2"],
    "otherprop": "singlevalue"
  }
}'

Submitting with flags#

Events can contain a set of flags, as defined in the Swagger API documentation.

Flags are accumulated on update, so updating an event with new flags will cause the event to contain the accumulated set of flags from all updates/submissions.

It is not possible to DELETE a flag through an event submission.

Warning

Some flags have special handling, called “partial flags”.

E.g. for the flag SOURCE_IS_CUSTOMERNET:

If an event is submitted without this flag, and then updated with this flag, the resulting event will be marked with the partial flag SOURCE_IS_PARTIAL_CUSTOMERNET

Submitting another update with SOURCE_IS_CUSTOMERNET will reset the flag of the event to SOURCE_IS_CUSTOMERNET.

#submit an event with properties
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
  "flags": ["SOURCE_IS_CUSTOMERNET"]
}'

Submitting a bulk of events#

When submitting many events, the bulk API is a more efficient solution.

The bulk API accepts a list of events, and an error mode.

The default error mode is rejectAll, which will reject the entire request with a 412 status if any event is invalid.
Alternatively, error mode dropInvalid will drop invalid events, and submit the valid events, before returning status 201.

In mode dropInvalid, the endpoint will drop events which fail to validate customer or location, or other referenced fields.
However, invalid JSON or invalid fields in the JSON request will still cause a 412 on the entire request.

The status result from the bulk endpoint will list the number of accepted and rejected events, as well as a list of submission status objects, one for each event.

#submit an event with properties
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event/bulk -d '{
  "events": [
    {"signature": "FirstAlarm"},
    {"signature": "SecondAlarm"},
    {"signature": "ThirdAlarm", "location": "invalid"}
  ],
  "onError": "dropInvalid"
}'

Response from bulk submit with dropped invalid events:

{
  "responseCode": 201,
  ...,
  "data": {
    "accepted": 2,
    "rejected": 1,
    "events": [
      {
        "id": "AGGR/1570715932641/1/f222ed6c-dc7b-473d-9bf0-20bb35cb1030",
        "status": "accepted",
        "message": null
      },
      {
        "id": "AGGR/1570715932642/1/3a38e04d-d58b-4d74-9c12-b41c4c435f97",
        "status": "accepted",
        "message": null
      },
      {
        "id": null,
        "status": "rejected",
        "message": "Invalid location: invalid"
      }
    ]
  }
}

The third event was invalid, and is therefore not assigned an ID. The order of the event status objects in the bulk status object will correspond to the events in the request.

Finalizing an event#

To finalize an event, submit the event with the finalized property.

Setting the finalized property has the same effect as adding the event flag FINALIZED.

#finalize this event
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event -d '{
  "id": "AGGR/1570715141521/1/1679fbfc-1792-4992-8428-3cb4df642fa8",
  "finalized": true
}'

Finalizing events prevents further updates on this event through later event submissions.

If an agent does not expect events to be updated, they should be finalized in the initial submission.