Auditing

The auditing interface consists of three parts:

  • The audit API resource returns URIs and URI templates to collections of audit records, so that they can be queried by criteria such as "all records from a particular user", or "all records from a particular application".
  • The audit record collection resource retrieves audit records and enables creating new audit records.
  • The audit record resource represents audit records that are individually queried.

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

Audit API

AuditRecords [application/vnd.com.nsn.cumulocity.auditApi+json]

Name Type Occurs Description
self URL 1 Link to this resource.
auditRecords AuditRecordCollection 1 Collection of all audit records.
auditRecordsForType AuditRecordCollection URI template 1 Read-only collection of all audit records of a particular type (placeholder {type}).
auditRecordsForUser AuditRecordCollection URI template 1 Read-only collection of all audit records for a particular user (placeholder {user}).
auditRecordsForApplication AuditRecordCollection URI template 1 Read-only collection of all audit records for a particular application (placeholder {application}).
auditRecordsForUserAndType AuditRecordCollection URI template 1 Read-only collection of all audit records of a particular user and type (placeholder {user} and {type}).
auditRecords ForUserAndApplication AuditRecordCollection URI template 1 Read-only collection of all audit records for a particular user and application (placeholder {user} and {application}).
auditRecords ForTypeAndApplication AuditRecordCollection URI template 1 Read-only collection of all audit records of a particular type and application (placeholder {type} and {application}).
auditRecords ForTypeAndUserAndApplication AuditRecordCollection URI template 1 Read-only collection of all audit records of a particular type, user and application (placeholder {type}, {user} and {application}).

GET the AuditAPI resource

Response body: application/vnd.com.nsn.cumulocity.auditApi+json

Required role: ROLE_AUDIT_READ

Example request: Retrieve AuditAPI resource

GET /audit
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditApi+json;ver=...
Content-Length: ...

{
  "self" : "<<AuditAPI URL>>",
  "auditRecords" : { "self" :"<<AuditCollection URL>>" },
  "auditRecordsForType" : "<<AuditCollection URL>>?type={type}",
  "auditRecordsForUser" : "<<AuditCollection URL>>?user={user}",
  "auditRecordsForApplication" : "<<AuditCollection URL>>?application={application}",
  "auditRecordsForUserAndType" : "<<AuditCollection URL>>?user={user}&type={type}",
  "auditRecordsForUserAndApplication" : "<<AuditCollection URL>>?user={user}&application={application}",
  "auditRecordsForTypeAndApplication" : "<<AuditCollection URL>>?type={type}&application={application}",
  "auditRecordsForTypeAndUserAndApplication" : "<<AuditCollection URL>>?type={type}&user={user}&application={application}"
}

Audit record collection

AuditRecordCollection [application/vnd.com.nsn.cumulocity.auditRecordCollection+json]

Name Type Occurs Description
self URI 1 Link to this resource.
auditRecords AuditRecord 0..n List of audit records, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev URI 0..1 Link to a potential previous page of audit records.
next URI 0..1 Link to a potential next page of audit records.

The "source" object of an audit record contains the properties "id" and "self".

POST - create a new audit record

Request body: AuditRecord

Response body: AuditRecord

Required role: ROLE_AUDIT_ADMIN

Example request:

POST /audit/auditRecords
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.auditRecord+json;ver=...
{
  "type" : "com_cumulocity_audit_LoginFailure",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Login failed after 3 attempts.",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "login",
  "severity" : "warning"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.auditRecord+json;ver=...
Content-Length: ...
Location: <<URL of new audit record>>
{
  "id" : "123",
  "self" : "<<URL of new audit record>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_audit_LoginFailure",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Login failed after 3 attempts.",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "login",
  "severity" : "warning"
}

The "id" and "creationTime" of the new audit record are generated by the server and returned in the response to the POST operation.

GET audit records

Response body: AuditRecordCollection

Required role: ROLE_AUDIT_READ

Example request: Retrieve audit records

GET /audit/auditRecords
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.auditRecordCollection+json;

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditRecordCollection+json;ver=...
Content-Length: ...
{
  "self" : "",
  "auditRecords" : [
    {
      "id" : "123",
      "self" : "<<AuditRecord 123 URL>>",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_audit_LoginFailure",
      "time" : "2011-09-06T12:03:27.845Z",
      "text" : "Login failed after 3 attempts.",
      "user" : "Spock",
      "application" : "Omniscape",
      "activity" : "login",
      "severity" : "warning"
    }
  ],
  "statistics" : {
    "totalPages" : 3,
    "pageSize" : 5,
    "currentPage" : 1
  }
}

In case of executing range queries on audit logs API, like query by dateFrom and dateTo, audits are returned in order from the last to the latest. It is possible to change the order by adding query parameter "revert=true" to the request URL.

DELETE - delete an collection of auditRecords

The DELETE method allows for deletion of auditRecords collections. Applicable query parameters are equivalent to GET method.

Request body: N/A

Response body: N/A

Required role: ROLE_AUDIT_ADMIN

Example request:

 DELETE: /audit/auditRecords ....
 Host: ...
 Authorization: Basic ...

Example response:

HTTP/1.1  204 NO CONTENT

Audit record

AuditRecord [application/vnd.com.nsn.cumulocity.auditRecord+json]

Name Type Occurs Description PUT/POST
id String 1 Uniquely identifies this audit record. No
self URI 1 Link to this resource. No
creationTime String 1 Time when audit record was created in the database. No
type String 1 Identifies the type of this audit record. POST: Mandatory PUT: No
time String 1 Time of the audit record. POST: Mandatory PUT: No
text String 1 Text description of the audit record. POST: Mandatory PUT: No
source ManagedObject 1 An optional ManagedObject that the audit record originated from, as object containing properties "id" and "self". POST: Mandatory PUT: No
user String 1 The user responsible for the audited action. Optional
application String 1 The application used to carry out the audited action. Optional
activity String 1 The activity that was carried out. POST: Mandatory PUT: Optional
severity String 1 The severity of action: critical, major, minor, warning or information. POST: Mandatory PUT: Optional
changes Set 0..1 An optional collection of objects describing the changes that were carried out. No
* Object 0..n Additional properties of the audit record. Optional

Please note that the source can contain not only ManagedObject with id and self, but in case of "Operation" type - operation id and in case of Alarm type - alarm Id. In such cases the self link in source is not correct, but it is kept there to not break the clients that expected to get ManagedObject in source.

GET an audit record

Response body: AuditRecord

Required role: ROLE_AUDIT_READ

Example request: Get a specific audit record

GET /audit/auditRecords/<<recordId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.auditRecord+json;

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditRecord+json;ver=...
Content-Length: ...

{
  "id" : "123",
  "self" : "<<AuditRecord URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_audit_LoginFailure",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Login failed after 3 attempts.",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "login",
  "severity" : "warning"
}