Skip to main content

Viewing history of asset

Accessing the history of an asset in Atlan is a flexible operation. This also makes it a bit more complex to understand than the other operations. To encapsulate the full flexibility of Atlan's search, the SDK provides a dedicated AuditSearchRequest object.

Similar but not identical to searching in general

Atlan's audit log that contains the history of an asset uses Elasticsearch. This makes the approach you use to access history similar to searching. However, there are differences as the audit log uses a different index than the broader search. If you're feeling brave, feel free to experiment with the more complex search mechanisms outlined in the searching section. But this should be sufficient to get you started with accessing asset history.

Build request​

To retrieve an asset's history in Atlan, you need to define the request. For simplicity, we provide helper methods to retrieve a defined number of entries in reverse-chronological order (most recent entries first).

By GUID​

To request the history of an asset by GUID:

Build the query by GUID
AuditSearchRequest request = AuditSearchRequest.byGuid( // (1)
        client, // (2)
        "6fc01478-1263-42ae-b8ca-c4a57da51392", // (3)
        10) // (4)
    .build(); // (5)
  1. Create a request for the history of an asset, by its GUID.
  2. Because this operation will directly look up the asset's history in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  3. Specify the GUID of the asset.
  4. Specify the amount of history (maximum number of activities). This will be in reverse-chronological order (most recent entries first).
  5. Build the request.

By qualifiedName​

To request the history of an asset by qualifiedName:

Build the query by qualifiedName
AuditSearchRequest request = AuditSearchRequest.byQualifiedName( // (1)
        client, // (2)
        Glossary.TYPE_NAME, "FzCMyPR2LxkPFgr8eNGrq", // (3)
        10) // (4)
    .build(); // (5)
  1. Create a request for the history of an asset, by its qualifiedName.
  2. Because this operation will directly look up the asset's history in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  3. Specify the type of the asset and qualifiedName of the asset.
  4. Specify the amount of history (maximum number of activities). This will be in reverse-chronological order (most recent entries first).
  5. Build the request.

To now run the search, we call the search() method against our request object:

Run the search
AuditSearchResponse response = request.search(client);
log.info(response.getCount()); // (1)
List<EntityAudit> results = response.getEntityAudits(); // (2)
  1. The getCount() method gives the total number of activities. Note that this could be smaller than the number requested, if fewer activities have occurred against the asset than the number used in the request.
  2. The details of each activity can be accessed through the getEntityAudits() method on the response.

Review details of each activity​

Each EntityAudit entry contains details of what occurred during an activity.

Contextual details​

To access contextual details about the activity:

Access contextual details about each activity
for (EntityAudit result : results)
}
if (detail instanceof AtlanTag)
}
if (detail instanceof CustomMetadataAttributesAuditDetail)
}
  1. You can safely type-check the detailed object. You could generically use Asset here instead of Table, but if you know the type of asset you've requested the history for then the detailed object should be the same detailed type.
  2. Once you've type-checked it, you can then coerce it.
  3. From there you can access any properties. Note that only properties actually set by the activity will have values in this detail object. So in this example, only if the description was actually changed to a new value would the description variable now have any content.
  4. This also means that if a field was actually removed (or cleared) by an activity you won't be able to distinguish that by just attempting to retrieve it. (It will be null whether it was removed by the activity or simply wasn't changed by the activity.) To distinguish what was actually removed by an activity, you need to use getNullFields(). The set returned by this method will contain the names of any fields that were actually removed (cleared) by the activity.
  5. You can then take whatever action you like if a field was removed (cleared) by checking for its existence within the getNullFields() set.
  6. You can type-check the detailed object to see if it's an Atlan tag.
  7. Once you've type-checked it, you can then coerce it.
  8. You can access the Atlan tag name using getTypeName().
  9. You can then compare this human-readable Atlan tag name to your expectations to take whatever action you like.
  10. You can type-check the detailed object to see if it details changes to custom metadata.
  11. Once you've type-checked it, you can then coerce it.
  12. You can access the name of the custom metadata using getTypeName().
  13. You can retrieve which custom metadata attributes were changed using getAttributes(). Since the result is a map, it will only contain attributes that were changed. If an attribute was removed (cleared) it will have a null value in the map but the name of the attribute will still be a key in the map. If a custom metadata attribute wasn't changed by the activity, it won't be a key in this map.
  14. You can then compare these human-readable names to your expectations to take whatever action you like.
Was this page helpful?