→ "Try it out - API Component "YADB""
→ check GitHub Python calls | Java Script calls | Java calls | Postman collection
This "How to" describes how to retrieve information on actions which have taken place around a document (object). Each action will be provided as single history entry for a stored document (object). In addition, the "How to" briefly describes which history entries are generated for a document (object) in general and what the structure looks like.
You can use the history of a stored document (object) to trace what actions happened from the creation of the document in the system, meaning the import, to the disappearance of the document from the system, the deletion. This also includes actions such as updating or retrieving the document (object).
{
"properties": {
"system:objectId": {
"value": 223439898
},
"system:objectTypeId": {
"value": "system:audit"
},
"system:baseTypeId": {
"value": "item"
},
"system:createdBy": {
"value": "353c631e-6a61-4e89-9512-8d275c826ce5"
},
"system:tenant": {
"value": "default"
},
"system:creationDate": {
"value": "2018-12-21T12:23:34.510Z"
},
"description": {
"value": ""
},
"action": {
"value": 101
},
"detail": {
"value": "CREATE_METADATA_WITH_CONTENT"
},
"referredObjectId": {
"value": "d3241d76-0652-4ac8-ba6d-892d719a2a6d"
},
"traceid": {
"value": "b279402aa9a2073b"
},
"system:versionNumber": {
"value": 1
}
}
}
A history entry is structured like a map, i.e. the entry consists of key-value pairs, whereby a value can also be a key-value pair.
Each history entry has an objectId and a referredObjectId.
The referredObjectId is the object ID of the document (object) for which the entry was written and the objectId is the object ID of the entry itself.
Furthermore there are properties like createdBy, detail or versionNumber, which indicate in what user context the entry was created, what happened and which version number the corresponding document has after the logged action.
The time of the action (creationDate) and the associated trace ID (traceid) are also saved to ensure traceability.
To retrieve the entire history of a stored document (object), you send a GET request to the URL /dms-core/objects/{objectId}/history with the objectId ("GET operation for a list of history entries by ID") endpoint).
String objectId = "1234567890"; //example-objectId
Request request = new Request.Builder()
.header("Ocp-Apim-Subscription-Key", key)
.url(baseUrl + "/dms-core/objects/" + objectId + "/history")
.get()
.build();
If you execute the request, using an OkHttpClient instance, you can display the result as a string in the command line.
Response response = client.newCall(request).execute(); System.out.println(response.body().string());
The returned history for a stored document (object) is a list of all history entries.
Responses
| Status Code | Meaning |
|---|---|
| 200 | OK |
| 401 | Unauthorized |
| 404 | Not Found |
For the various actions, such as import, retrieve, update, and delete, there are the following history entries (action field values):
Import
Delete
Update
Retrieve
If a deletion action is triggered, the document to be deleted is first marked as deleted so that it can no longer be found. Only then are metadata and content file actually deleted, and a corresponding entry is made in the history of the document.