Audit trails

Search Trails

This is the endpoint used to manage the audit trails.

Search Trails

POST https://api.everisbigcontent.com/edms/audit/v1/trails/search

Retrieve audit trails given a set of condition.

Note that audit trails can belong to a domain or to a document store. To specify which one we are looking for, we need to specify it through the header.

The document store trails are all generated by events related directly to actions that happen in a document store. Some examples of document store events are create document, search documents or download current version.

The domain trails are all generated by events that do not depend on a document store. Currently, only authentication events apply to this category. That is, create token and search trails.
Note however, that all the domain events are propagated to all document stores contained to which the user has access. So, if a user makes a create token, the event will be registered both as a domain event and as document store event (only for document stores in which the user has access).

Finally, only users with appropriate access rights can search for audit trails. Note document stores and domains can have different access groups. Users that want to search in both document store and domain audit trails must be assigned the respective groups as RW.

We must set in the audit configuration the events that we would like to track.

Parameters

HTTP Headers

HTTP headers allow pass additional information with the request or the response. BigContent headers are used for recurrent details like authentication or document store.

Table 1. Headers
Name	Example	Description
`Domain or Document-Store`	If Domain: `gds4et7gfds4h9ewjt1fds964f` if Document-Store: `invoice_store`	This operation can be performed either in a domain or in a document store. Only one of these headers can be sent
`Authorization`	`Bearer ha9r6DG4e5AQ84gferAd8EQ…`	Mandatory header of String type that authorizes you as the user with the right to execute this operation. The string is a Bearer Token returned from the operation create token
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`

Body

As indicated by headers, the body of the http request must be a JSON object.

limit is a preview feature subject to change.

Condition List

{
  "conditions": [   (1)
    {
      "field": "objectId",
      "operand": "eq",
      "value": "qga8r5hsy9rw5weggf93lopa58"
    }
  ],
  "orderBy": {
     "asc": true,
     "fields": [
       "date"
     ]
   },
   "limit": 5000
  ]
}

1	A least one valid condition is required

Table 2. Conditions
Field name	Possible values	Detail
field	`id`, `date`, `authorizedUser`, `spanId`, `name` or `objectId`	The field of the audit trail to match. Note that when using id as field it refers to the identifier of the trail. objectId refers to the identifier of the object to which the event was applied (e.g. a document)
operand	`eq`, `gt` and `lt`	Type of comparison that the search will apply. If not specified, `eq` is applied
value	Anything to search for	The value we are looking for

Even though domain or documentStore are fields of the event, these cannot be used as condition fields. They must be sent in the header.

Table 3. Condition operand
Operand	Detail
`eq`	The value needs to be exactly the same as the searched
`gt`	The value needs to be grater than the searched
`lt`	The value needs to be lower than the searched

Table 4. OrderBy
Field name	Possible values	Detail
asc	Boolean (`true`, `false`)	`true` by default. If set to `false` the result of the search will be ordered in descendent order
fields	List of `Strings`	The result will be ordered taking into account the values of those fields. If more than one is provided, it will order it by the first one. Then, all the documents with the same value for the first field will be ordered by the value of the second field. This process will continue until all the fields of the list have been taken into account

Table 5. Limit
Field name	Possible values	Detail
limit	Integer (e.g. `5000`)	If `true` the result of the search will be ordered in ascendant order

limit is a preview feature subject to change.

Responses

Success

Successful responses can be easily identified being always 20x (e.g. 200, 201).

Table 6. Success response
Field	Example	Description
Status code	`200`	`OK`
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`
Body	JSON response	A JSON array containing the audit events

JSON response

{
  "values": [
    {
      "id": "i36hdw5g2ibjzh5tz2h5esiii4",
      "documentStore": "invoice_store",
      "date": "2018-07-09T14:50:07.826Z",
      "authorizedUser": "john@company.com",
      "accessUser": "john@company.com",
      "spanId": "01b46bfb-8888-8888-8888-0b1e3312d7ea",
      "event": "TOKEN_CREATE",
      "objectId": "npq65fmipabopjknqbaknxaepe"
    },
    {
      "id": "kjng95267tmxmz1kqo0137kdje",
      "documentStore": "invoice_store",
      "date": "2018-06-08T10:32:40.615Z",
      "authorizedUser": "john@company.com",
      "accessUser": "john@company.com",
      "spanId": "01de9c54-8888-8888-8888-914dc1b9e88d",
      "event": "DOCUMENT_CREATE",
      "objectId": "5pzpftotinhmbhnlaj65nito64"
    },
    {
      "id": "9m54y9y940143734yt81327468",
      "documentStore": "invoice_store",
      "date": "2018-06-08T10:35:11.332Z",
      "authorizedUser": "john@company.com",
      "accessUser": "john@company.com",
      "spanId": "01de9c54-8888-8888-8888-914dc1b9e88d",
      "event": "DOCUMENT_DELETE",
      "objectId": "fotud8totinhmcinkej65nito64",
      "ed": {
        "deleteType": "metadata_deletion"
      }
    }
  ],
  "size": 3
}

Table 7. Event List
Name	Value	Detail
values	JSON array of events	List of events that apply the conditions of the search
size	3	Number of elements in the JSON array

Table 8. Audit trails fields
Name	Value	Detail
id	`i36hdw5g2ibjzh5tz2h5esiii4`	Event identifier
documentStore	`invoice_store`	The document store in which the event took place
date	`2018-07-09T14:50:07.826Z`	The date at which the event took place. The format we follow is yyyy-MM-ddTHH:mm:ss.SSSZ. The "T" is used to separate date and time, and the Z is the zone designator for the zero UTC offset
authorizedUser	`john@company.com`	User who performed the operation
accessUser	`john@company.com`	User who performed the operation
spanId	`01de9c54-8888-8888-8888-914dc1b9e88d`	Id to track operations
event	`DOCUMENT_CREATE`	Name of the event
objectId	`fotud8totinhmcinkej65nito64`	Id of the object in which the operation was performed
extended	`{"deleteType": "metadata_deletion"}`	A JSON that holds extra information about the event. See extended details table below.

Here is the list of events that record additional information in the extended field.

Table 9. Extended information details
Event	Extended fields	Extended details
`DOCUMENT_DELETE`	`deletionType`	The deletion type applied.
`DOWNLOAD_VERSION`	`version`	Version being downloaded in the format `{major}.{minor}`. Downloading thorough a link also triggers this event.
`VERSION_NEW`	`version`	Version being created in the format `{major}.{minor}`.
`VERSION_UPDATE`	`version`	Version being updated (overridden) in the format `{major}.{minor}`.
`VERSION_DELETE`	`version`, `deletionType`	Version being deleted in the format `{major}.{minor}`. The deletion type applied.
`CATEGORY_DELETE`	`deletionType`	Always `metadata_deletion`. Categories are not recoverable.
`VERSION_METADATA_GET`	`version`	Version being retrieved in the format `{major}.{minor}`.
`VERSION_SET_CURRENT`	`version`	Version being updated as current in the format `{major}.{minor}`.
`SEARCH`	`query`	Original JSON sent with the search conditions.
`LINK_CREATE`	`version`	Only when specified in the request. Version being associated with the generated link in the format `{major}.{minor}`.

Error

In case of error, the response body contains a JSON object with additional information:

span-id: auto-generated identifier of the request. Please provide this when asking for support in our forum.
message: descriptive message of the error. This is aimed for developers and is specially important for Bad Request errors., where contains hints on how to fix the request.

Error messages should not be used to validate errors since they may be subject to change.

Example

{
  "span-id" : "7eb38962-2618-85f9-brte-4f15f6729590",
  "message" : "No match found for the Id"
}

Table 10. Error messages
Status code	Message	Description
400	`Conditions cannot be empty`	The field conditions of the body request is mandatory
400	`Malformed JSON exception (line _, col _): …`	The JSON body has a bad structure. Message points where is the problem with line and column numbers as well as what is the problem (e.g. double "{", or a missing ",", …)
400	`Malformed JSON exception (line _, col _): Invalid UTF-8 middle byte…`	The encoding used to send the object was not `UTF-8`. This error can happen due to launching a curl in git-bash
401	`The Token has expired on…`	Has passed more than an hour since the last create token or refresh token operation
401	`Malformed token`	The token sent is not valid
401	`Problems parsing token`	An empty token has been sent
401	`The Document-Store header must be set`	The header indicating the document store that you want to access, must be set
415	`Content type _ not supported`	The Content-Type header is not correctly set
500	`Internal server error`	If it happens consistently, please report it on our forum

Code examples

cURL
Java
Node.js

curl "https://api.everisbigcontent.com/edms/audit/v1/trails/search/" \
-X POST \
-H "Authorization: Bearer ha9r6DG4e5AQ84gferAd8EQ..." \
-H "Document-Store: invoice_store" \
-H 'Content-Type: application/json' \
-d '{"conditions": [{ "field": "name", "value":"DOCUMENT_CREATE"}]}

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

String url = "https://api.everisbigcontent.com/edms/audit/v1/trails/search";
String token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
String documentStore = "invoice_store";

HttpPost post = new HttpPost(url);
post.setHeader("Authorization", token);
post.setHeader("Document-Store", documentStore);

StringEntity json = new StringEntity("{\"conditions\": [{ \"field\": \"name\", \"value\":\"DOCUMENT_CREATE\"}]}");
json.setContentType(ContentType.APPLICATION_JSON.toString());

post.setEntity(json);

CloseableHttpClient client = HttpClients.createDefault();
CloseableHttpResponse execute = client.execute(post);
HttpEntity entity = execute.getEntity();

String jsonResponse = EntityUtils.toString(entity, StandardCharsets.UTF_8);

var request = require('request');
var token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
var documentStore = "invoice_store";

request.post({
    headers: {
      "Authorization": token,
      "Document-Store": documentStore
    },
    url: "https://api.everisbigcontent.com/edms/audit/v1/trails/search",
    json : {"conditions": [{ "field": "name", "value":"DOCUMENT_CREATE"}]}
  }, function(error, response, body){
  console.log(body);
});

By document Id

{
  "conditions": [
    {
      "field": "objectId",
      "operand": "eq",
      "value": "qga8r5hsy9rw5weggf93lopa58"
    }
  ]
}

This returns all the trails that happened to the document specified since its creation.

By event

{
  "conditions": [
    {
      "field": "name",
      "operand": "eq",
      "value": "DOCUMENT_CREATE"
    }
  ]
}

This returns all the create document trails.

By trail Id

{
  "conditions": [
    {
      "field": "id",
      "operand": "eq",
      "value": "i36hdw5g2ibjzh5tz2h5esiii4"
    }
  ]
}

This returns the trail with the specified id.

By date range Dates

{
  "conditions": [
    {
      "field": "date",
      "value":"2018-11-09T11:30:00.000Z",
      "operand": "gt"
    },
    {
      "field": "date",
      "value":"2018-11-09T11:35:00.000Z",
      "operand": "lt"
    }
  ]
}

This will return all the trails that happened between 2018-11-09T11:30:00.000Z and 2018-11-09T11:35:00.000Z.