Store events

The Event API provides a /put endpoint for storing your own events in 10Duke Enterprise in JSON format. JSON Web Signatures (JWS) are used for authorizing requests and to convey the event data.

In addition to events that follow the data schema of events written by 10Duke Enterprise, you can store your own custom events. You must always include the envelope part according to the data schema, but the data part can contain any data fields needed.

We recommend that you follow the data schema in custom events where applicable, for example, in event timestamps and error fields, so that analysis tools are able to handle all events in a similar manner.

Specify applicable “feed” information for your custom events, which is used later when reading the events:

  • Assign event source IDs to the events as needed in order to divide them into separate event sources in 10Duke Enterprise. This allows you to later read data from a specific event source as needed.

  • 10Duke Enterprise uses the event object type and ID to identify users. This makes it easier to tell what information has been stored for a specific user and, for example, in the EU fulfill legal requirements. In your own custom events, you can use the event object type and ID for identifying the user or any other entity relevant to the events.

Requests

Send a POST request containing one or multiple events to the /put endpoint at the event data service URL in your 10Duke Enterprise environment.

The request format (line breaks added for display purposes):

POST /put
   Content-Type application/jose

   [Base64-encoded JWS with event data]

See more information in the API reference.

Example event data

Here are some examples of event data that you wrap in the JWS.

An example event that contains envelope fields and the data fields specific to this (custom) type of event. If eventId is not specified, 10Duke Enterprise generates an ID for the event.

{
   "eventSourceId": "my-application",
   "eventId": "bf3463bf-4fa2-4602-a15c-d302b1ec1879",
   "eventType": "login",
   "data": {
      "ipAddress": "12.13.14.15",
      "userId": "0f58aa7a-c10a-4835-a4d5-431a21d34a59",
      "email": "john.smith@example.com"
   }
}

An example with two events:

[
   {
      "eventSourceId": "my-application",
      "eventId": "4c16ea57-285b-4340-aef0-73aa2b534ead",
      "eventType": "feature_use",
      "data": {
         "action": "open",
         "featureNameId": "open_model",
         "modelId": "4ac9ce00-ee87-4082-a5d2-d71a03055ded",
         "eventAuthorId": "4be7d70b-ea29-40dd-a21e-0ac5304dc232",
         "eventAuthor": "user-1",
         "eventCreated": "2018-03-15T15:10:00Z"
      }
   },
   {
      "eventSourceId": "my-application",
      "eventId": "b05a5b27-308f-4f9d-a056-66fa64e2ece7",
      "eventType": "feature_use",
      "data": {
         "action": "execute",
         "featureNameId": "analyze_model",
         "modelId": "4ac9ce00-ee87-4082-a5d2-d71a03055ded",
         "eventAuthorId": "4be7d70b-ea29-40dd-a21e-0ac5304dc232",
         "eventAuthor": "user-1",
         "eventCreated": "2018-03-15T15:23:00Z"
      }
   }
]

Authorize requests

To provide the event data and to authorize the request, create a JSON Web Signature (JWS):

Set the event data as the JWS payload.

In the JWS header, set alg to RS256, RS384, or RS512. The algorithm to use depends on the length of the RSA keys used for authorization.

{
   "alg": "RS256"
}

Now sign the JWS with the private key of the client storing the data. You get something like this:

eyJhbGciOiJSUzI1NiJ9.eyJldmVudFNvdXJjZUlkIjoibXktYXBwbGljYXRpb24iLCJldmVudElkIjoiYmYzNDYzYmYtNGZhMi00NjAyLWExNWMtZDMwMmIxZWMxODc5IiwiZGF0YSI6eyJpcEFkZHJlc3MiOiIxMi4xMy4xNC4xNSIsInVzZXJJZCI6IjBmNThhYTdhLWMxMGEtNDgzNS1hNGQ1LTQzMWEyMWQzNGE1OSIsImVtYWlsIjoiam9obi5zbWl0aEBleGFtcGxlLmNvbSJ9LCJldmVudFR5cGUiOiJsb2dpbiJ9.dmzGW4mMRen...

Include the JWS as the request body in the POST request.

Responses

If the request is successful, 10Duke Enterprise returns an empty response with HTTP status code 200.

An error response provides a relevant HTTP status code in the 400 or 500 series.

See more information in the API reference.