Skip to main content

Using the Correlation Id Header

When API clients make calls, there is an optional Header that can be passed in the HTTP request. Along with the standard parameters:

  • x-tenant-id
  • authorization

Clients can also pass a header containing a Correlation Id so they can track the outcomes of those calls specifically against the corresponding event notifications issued as a result of the API call. The header is called x-correlation-id and can contain a client provided string.

Typical Use Case for the Correlation Header​

Correlation Id Use Case
As an API consumer:

      GIVEN: I am monitoring Event Notifications issued from the Fenergo SaaS Platform.

      AND: I want to identify which, of my API calls, has resulted in the issuing of a specific event

      WHEN:  I pass in a Correlation Id into an API call

 THEN:  I want to the corresponding Event Notification to reference that Correlation Id.

Using the Correlation with Postman​

As illustrated below, the header is being set in postman and a string "Test-CorrelationId" is passed in for the value. This will be sent as part of the API call (in this case the Entity Data Command API for creating a new Entity). When event notifications are issued this value will be referenced and enables downstream monitoring and tracing of API calls and their status.

The below is the body of the Event Notification sent once the above API call is made. The "CorrelationId":"Test-CorrelationId" can be seen and used to determine the origin of the call.

Event Notification for API Call
    {
        "Id": "09916cea-78b8-524c-a6ad-bd7397bcd4e6",
        "TenantId": "45bf62ac-e4b1-4c16-ae32-d774cd18db6d",
        "EventType": "entitydata:created",
        "RelativeUrl": "entitydataquery/api/entity/9b22ae41-3f0a-4c68-a332-8669705ee3ec",
        "Payload": {},
        "When": "2023-11-12T17:18:55+00:00",
        "CorrelationId": "Test-CorrelationId",
        "CausationId": "c780df56-5aa8-4d64-b9fd-3560d75817c8"
    }

Supported Command Domains​

Event Notifications are supported across a number of domains in Fenergo and more are being added as the product is enhanced and updated. Currently the following Command APIs can accept the x-correlation-id header and will reference the value in any corresponding notifications: