Skip to main content

Introduction to Audit API

The purpose of this document is to provide guidance for working with FenX Audit API response. Full API documentation is available on the documentation portal.

Audit Response​

Using the ~/journeyquery/api/auditevent/resources, audit events for specified list of resources can be queried.

Using the ~/journeyquery/api/auditevent/searchterm, audit events for specified list of resources containing provided search term can be queried.

Every audit query response will contain one or many events.

Sample Audit Event​

Sample Audit Event
{
      "eventId": "dce42013-6bd1-5730-bb86-421b175fxxxx",
      "resourceId": "a800bdf5-8044-4d26-8af8-b4934e56xxxx",
      "resourceType": "Entity",
      "entityReferenceId": "a800bdf5-8044-4d26-8af8-b4934e56xxxx",
      "journeyReferenceId": null,
      "eventType": "EntityCreated",
      "eventSubType": null,
      "beforeValue": {},
      "afterValue": {},
      "version": "0",
      "date": "2021-10-08T11:49:09+00:00",
      "userId": "8866c334-e961-496c-992f-9372407axxxx",
      "clientId": "fenergo-nebula-admin-tool",
      "service": "EntityData",
      "tenant": "c73749a2-9d9c-4050-bd84-7cc5bd0axxxx",
      "correlationId": "cb24a366-5930-4ae9-9750-1a54b1fexxxx",
      "metadata": {
        "userName": "test.user@fenergo.com",
        "journeyName": ,
        "eventName": "Entity Created",
        "taskReassignedUserBefore": null,
        "taskReassignedUserAfter": null,
        "taskReassignedTeamNameBefore": null,
        "taskReassignedTeamNameAfter": null,
        "completedByNameBefore": null,
        "completedByNameAfter": null,
        "dateIsoFormat": "2021-10-08 11:49:09"
      }
    }

Single event object will contain, among others, information regarding resourceType, resourceId and eventType for given resource.

In this example we can see it's EntityCreated event type for Entity resource type.

beforeValue and afterValue​

Important concept to understand is that purpose of Audit event is to record and show changes done on a resource object (Entity, Journey etc.) and not to display information regarding that object.

Changes done to resource object are recorded in beforeValue and afterValue properties.

  "beforeValue": {
    "Properties": { "firstName": { "Value": "testdata" } },
    "Version": 0
  },
  "afterValue": {
    "Properties": { "firstName": { "Value": "testname" } },
    "Version": 1
  }

This example shows that there was action taken on a Entity resource which resulted in updating resource's firstName from testdata to testname and versions respectively.

Journey type specific structure​

Journey resource type has a complicated structure divided by Stages, Processes and Tasks (Please refer to Journey documentation).To record and display changes on Journey resource there is a hierarchy of key-value pair objects drilling down from Stages to Tasks level.

Every event with this structure has journey metadata property included in afterValue which supplements response with stage, process and task names

      "beforeValue": {
        "Stages": {
          "\u0022947d987e-2d4c-4642-b65a-7588f7a6e133\u0022": {
            "Processes": {
              "\u002242a21741-d6cb-41b5-a4a1-eb26becc4754\u0022": {
                "Tasks": {
                  "\u0022ef6ccff3-9b2a-4a35-9535-3b94f9487b8a\u0022": {
                    "Status": "In Progress",
                    "Completed": "0001-01-01T00:00:00",
                    "CompletedBy": null,
                    "IsCompleted": false
                  }
                }
              }
            }
          }
        },
        "Version": 5
      },
      "afterValue": {
        "Stages": {
          "\u0022947d987e-2d4c-4642-b65a-7588f7a6e133\u0022": {
            "Processes": {
              "\u002242a21741-d6cb-41b5-a4a1-eb26becc4754\u0022": {
                "Tasks": {
                  "\u0022ef6ccff3-9b2a-4a35-9535-3b94f9487b8a\u0022": {
                    "Status": "Done",
                    "Completed": "2021-10-08T12:07:54.7693637Z",
                    "CompletedBy": "8866c334-e961-496c-992f-9372407a810f",
                    "IsCompleted": true
                  }
                }
              }
            }
          }
        },
        "Version": 6,
        "metadata": {
          "Stages": [
            {
              "Id": "947d987e-2d4c-4642-b65a-7588f7a6e133",
              "Name": "Screening",
              "Processes": [
                {
                  "Id": "42a21741-d6cb-41b5-a4a1-eb26becc4754",
                  "Name": "New Request",
                  "Tasks": [
                    {
                      "Id": "ef6ccff3-9b2a-4a35-9535-3b94f9487b8a",
                      "Name": "Basic Details"
                    }
                  ]
                }
              ]
            }
          ]
        }

Above example indicates that action performed on Journey resource resulted in an audit event that updated several fields belonging to Task: ef6ccff3-9b2a-4a35-9535-3b94f9487b8a.

"Tasks": {
    "\u0022ef6ccff3-9b2a-4a35-9535-3b94f9487b8a\u0022": {
    "Status": "Done",
    "Completed": "2021-10-08T12:07:54.7693637Z",
    "CompletedBy": "8866c334-e961-496c-992f-9372407a810f",
    "IsCompleted": true
    }
}

This Task belongs to Process: 42a21741-d6cb-41b5-a4a1-eb26becc4754

"Processes": {
    "\u002242a21741-d6cb-41b5-a4a1-eb26becc4754\u0022": {

and the Process belongs to Stage: 947d987e-2d4c-4642-b65a-7588f7a6e133.

"Stages": {
    "\u0022947d987e-2d4c-4642-b65a-7588f7a6e133\u0022": {

Metadata​

Every event has a meatdata property with additional information:

"metadata": {
    "userName": "test.user@fenergo.com",
    "journeyName": "Screening Individual",
    "eventName": "Entity Created",
    "taskReassignedUserBefore": "test.user@fenergo.com",
    "taskReassignedUserAfter": "test.user1@fenergo.com",
    "taskReassignedTeamNameBefore": "TestTeam1",
    "taskReassignedTeamNameAfter": "TestTeam1",
    "completedByNameBefore": test.user@fenergo.com,
    "completedByNameAfter": test.user@fenergo.com,
    "dateIsoFormat": "2021-10-08 11:49:09"
    }
  • userName - username for userId property,
  • journeyName - journey name for journeyReferenceId property in Entity type event,
  • eventName - event name friendly format for search capabilities,
  • taskReassignedUserBefore - specific for TaskReassigned journey event, provides username for AssignedTo property in beforeValue section,
  • taskReassignedUserAfter - specific for TaskReassigned journey event, provides username for AssignedTo property in afterValue section,
  • taskReassignedTeamNameBefore - specific for TaskReassigned journey event, provides team name for TeamId property in beforeValue section,
  • taskReassignedTeamNameAfter - specific for TaskReassigned journey event, provides team name for TeamId property in afterValue section,
  • completedByNameBefore - username for CompletedBy property in beforeValue for Journey type event,
  • completedByNameAfter - username for CompletedBy property in aftereValue for Journey type event,
  • dateIsoFormat - UTC date in frindly format for search capabilities