Structure of a message

ID's

traceId

The trace id is a id, which will be used for one complete process.

As an example:

The Frontend makes a url request, which invokes a service function A. The service function A invokes a service function B. Service function A is returning a result back to the frontend. There is also a subscription C which listens for success responses of service A.

The traceId will be the same for all the messages and responses between the frontend, different service functions and subscriptions.

This allows to track the whole flow.

instanceId

The instance id is the unique id of the current event bridge (client) instance. This id is auto generated by default, but can be set as config parameter. This id might be used by some event bridge adapter. It can also be used for monitoring.

correlationId

The correlation id is a unique id that is used for a request (command) message and the corresponding response. While the traceId stays the same for a whole process flow, the correlationId is only valid and used for a single call.

id (message id)

Each message has a unique id, which might be used by the underlying event bridge/infrastructure or for persistence purposes.

principalId

The principal id is an optional field, which can be set by business logic to the user id. The principal id should be some technical user id and not something like an email, as it might be logged. It is recommended to use the message principal id for any authentication/authorization, because this way, there is no need to look into the message payload, which might be encrypted or not present.

The principal id is propagated down - like the trace id - in the whole process flow. So it will be available in subscriptions and function invocations. Each message has a unique id, which might be used by the underlying event bridge/infrastructure or for persistence purposes.

tenantId

The tenant id is an optional field, which can be set by business logic to the tenant id. The principal id should be some technical tenant id and not something like an company name, as it might be logged.

The tenant id is propagated down - like the principal id - in the whole process flow. So it will be available in subscriptions and function invocations. Each message has a unique id, which might be used by the underlying event bridge/infrastructure or for persistence purposes.

Message structure

As PURISTA is a message based framework, the structure of messages might be interesting.

field	required	description
messageType	yes	the type of message eg. command, response, custom...
id	yes	the unique id off a single message
timestamp	yes	the timestamp as number in ms when the message was created
correlationId	only used in Command and CommandResponse messages	a unique id generated when a comman message is send. the command response is using same correlationId
principalId	no	the unique id of the user
tenantId	no	the unique id of the tenant
eventName	no	a string representing the business event name
sender	yes	the service function or subscription who sends the message
sender.serviceName	yes	the service name
sender.serviceVersion	yes	the service version
sender.serviceTarget	yes	the service function or subscription name
sender.instanceId	yes	the unique id of the event bridge instance which sends the message
receiver	depends on message type	the service function or subscription who should receive the message
receiver.serviceName	only for commands & responses	the service name
receiver.serviceVersion	only for commands & responses	the service version
receiver.serviceTarget	only for commands & responses	the service function or subscription name
receiver.instanceId	only for command responses	the unique id of the event bridge instance which receives the message
payload	depends on message type	the message payload (business data)
otp	no	OpenTelemetry context propagation as json stringified string