REST API for Monitoring (version 1)

Below is presented the available REST API related to monitoring event data.

If any request to the API presented on this page is considered as not monitored according to the inclusions and exclusions rules, it will be responded with error code 403.

POST /lumis/api/rest/lumis/monitor/v1/events/{eventId}/data

Adds an occurrence of a monitored event.

The persistence of the information may occur asynchronously, so a successful response to this operation indicates that the addition request was accepted, but problems with the provided information or the environment may prevent it from being actually persisted.

Request Headers

This operation requires headers in the request compatible with:

Request Parameters

Request Body

The request body must be a JSON object with values for the fields of the event being recorded. Values for fields that are not in the event definition will not be stored.

The type of the JSON value must be compatible with the type of the event field, as per the table below:

In the case of a multi-valued field, the value must be an array of the corresponding type. In the case of a complex field, the value must be an object (or array of objects if it is a multi-valued complex type) containing the values for its internal fields.

Some fields when filled can generate default values for other fields if these have not been explicitly specified. The ability to generate or not generate the value for other fields depends on whether it was possible to infer from their value what the corresponding value of the others would be. The table below lists which fields can generate which other fields:

This generation of default values can occur in a cascade. For example, lum_client.url can generate a default value for lum_webresource.rendered.path, which in turn can generate a default value for lum_page.id, which can in turn generate a default value for lum_page.channel.id, which can in turn generate a default value for lum_page.channel.*.

The field lum_page.channel.id has as a default value the identifier of the root channel of the website corresponding to the URL utilized in the request for this operation. This default value will only be used if the field is not present in the body and has not been inferred from another field. In the case of this default value being used, it will also be used to generate values for deduced fields from this, as presented in the table above.

The field lum_event.datetime has as a default value the current time. To make lum_event.datetime more consistent with the server's clock for this operation, it is recommended to use the lum_event.datetime.offset field instead of the absolute time in lum_event.datetime when indicating that the event occurred some known time ago. The value of the lum_event.datetime.offset field represents a time variation in milliseconds and its value must be a non-negative integer. When this field is used, the lum_event.datetime field is calculated subtracting the offset from the current time.

Except for lum_user.trackId, the fields lum_user.* cannot be specified directly. They will be calculated based on the value obtained for the field lum_user.trackId.

The project identifier (lum_event.projectId), if not present in the collection, will be inferred from the following fields in the given order:

1. lum_page.channel.id
2. lum_serviceinstance.channel.id
3. lum_website.id

Success Response

The response to this operation in case of success will be an empty body and a response code of 204.

Error Response

This operation responds with the standard JSON error object.

If there is no corresponding event for the specified identifier, the response code will be 404.

If the event is disabled, the response code will be 409.

Request Example

In the example below, an occurrence of a custom event with identifier my.custom.event is registered. Assuming that this event is already defined in the portal and has several native fields and some custom ones. In this example, we are assuming that several native fields may be identified based on information that the browser naturally includes in the request. Note that this call will only be able to correctly fill these fields automatically if it is triggered from the page where the event occurred and if the browser included the expected default information, such as Referer, Cookie, User-Agent headers.

POST /lumis/api/rest/lumis/monitor/v1/events/my.custom.event/data?fromEventClient=true HTTP/1.1
Content-Type: application/json
Accept: application/json
(... other headers ...)

{
  "lum_client": {
    "origin": {
      "url": "http://www.example.org/referer_of_current_page"
    }
  },
  "my_custom_event_data": {
  	"field1": "some value",
  	"field2": "2016-09-03T13:00Z",
  	"field3": 12345
  }
}

In the example below, a similar occurrence to the one above is registered, but specifying several fields that in the previous example would have been deduced directly from the data naturally included in the request by the browser.

POST /lumis/api/rest/lumis/monitor/v1/events/my.custom.event/data?fromEventClient=false HTTP/1.1
Content-Type: application/json
Accept: application/json
(... other headers ...)

{
  "lum_client": {
    "lumisClientId": "4028E38161D8ACCD0161D8AE730804ED",
    "httpSessionId": "4BF0922714E97A71D8B575F9CAE3F366",
    "origin": {
      "url": "http://www.example.org/referer_of_current_page"
    },
    "ip": "127.0.0.1",
    "userAgent": {
        "string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0"
    },
    "lumisUserSessionId": "02KmNRsaHpR3dJ2abxK7toklmhpj5zDc",
    "locale": "en_US",
    "url": "http://www.example.org/my_current_page/"
  },
  "lum_server": {
    "id": "LumisPortalServer"
  },
  "lum_user": {
    "trackId": "qmIb4Glytq-F2_zSe66Pa3ypEWtP4LXb"
  },
  "my_custom_event_data": {
  	"field1": "some value",
  	"field2": "2016-09-03T13:00Z",
  	"field3": 12345
  }
}