AuditLog

View as Markdown

AuditLog

The AuditLog class reads the audit log of a stack, a record of the activities that users performed on its content, such as publishes, updates, and deletes.

When to Use This Class: Use this class to find out who changed or published content, and when.

Conceptual Role: Acts as the Content Management API (CMA) client for the /audit-logs endpoint. Call stack.AuditLog() to get an instance.

Returns: AuditLog. An object for audit log operations.

Instance State

The UID you pass to stack.AuditLog() decides which methods you can call on the instance:

  • Call stack.AuditLog() without a UID to list the log with FindAll or FindAllAsync.
  • Call stack.AuditLog("<AUDIT_LOG_UID>") to read one log item with Fetch or FetchAsync.

If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. Both wrong cases throw the same exception type.

Warning The SDK treats an empty string as no UID. stack.AuditLog("") allows FindAll, which then sends its request to /audit-logs/ with a trailing slash. Call stack.AuditLog() with no argument when you mean the whole log.

Class-Level Notes

Authentication.

  • stack.AuditLog() throws InvalidOperationException when the client has no authtoken and the stack has no management token.
  • The CMA reference accepts a management token or an Open Authorization (OAuth) token for audit log requests.

Retention.

  • The CMA reference states that the audit log returns activities from the 30 days before the current day.

Responses.

  • Both methods return the raw API response as a ContentstackResponse. Read it with OpenJsonObjectResponse().

Capability Matrix

CapabilitySupportedNotes / Alternative
Write to or delete from the audit logNoThe API records activities. The CMA reference lists read requests only.

Method Index

List the log. Available on stack.AuditLog() when you pass no UID.

Method NameReturnsDescription
FindAllThe API response with the audit log items.Lists the items in the audit log.
FindAllAsyncThe API response with the audit log items.Lists the items in the audit log asynchronously.

Read one item. Available on stack.AuditLog("<AUDIT_LOG_UID>").

Method NameReturnsDescription
FetchThe API response with the requested audit log item.Retrieves one log item.
FetchAsyncThe API response with the requested audit log item.Retrieves one log item asynchronously.

Class-Level Snippet

This snippet lists the audit log with the branch key, then fetches one log item.

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse log = await client.Stack("<API_KEY>").AuditLog().FindAllAsync(collection);
    Console.WriteLine(log.OpenJsonObjectResponse().ToJsonString());

    ContentstackResponse item = await client.Stack("<API_KEY>").AuditLog("<AUDIT_LOG_UID>").FetchAsync();
    Console.WriteLine(item.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the AuditLog class has its own section below, with its parameters, validation rules, behavior, and examples.

Fetch

Fetch retrieves one item from the audit log of the stack.

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response with the requested audit log item.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
  • Throws InvalidOperationException if the instance has no UID, because Fetch reads one log item. Call stack.AuditLog("<AUDIT_LOG_UID>").
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one GET request to /audit-logs/<AUDIT_LOG_UID>. See Get audit log item in the Content Management API (CMA) reference.
  • The CMA reference states that the audit log covers the 30 days before the current day.
  • Adds the entries of collection to the query string. null or an empty collection adds none.
  • Returns the raw API response.

Example

Basic usage: fetch one audit log item

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").AuditLog("<AUDIT_LOG_UID>").Fetch();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: fetch a log item with the branch key

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").AuditLog("<AUDIT_LOG_UID>").Fetch(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Authentication: use a management token instead of an authtoken

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").AuditLog("<AUDIT_LOG_UID>").Fetch();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

FetchAsync

FetchAsync retrieves one item from the audit log of the stack, without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the requested audit log item.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
  • Throws InvalidOperationException if the instance has no UID, because FetchAsync reads one log item. Call stack.AuditLog("<AUDIT_LOG_UID>").
  • The SDK throws the client-side exceptions above when you call FetchAsync, before it returns a task. An API rejection surfaces when you await the task.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Completes the task when the API responds.
  • Otherwise behaves like Fetch.

Example

Basic usage: fetch one audit log item

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").AuditLog("<AUDIT_LOG_UID>").FetchAsync();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: fetch a log item with the branch key

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").AuditLog("<AUDIT_LOG_UID>").FetchAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

FindAll

FindAll retrieves the audit log of the stack, a record of the activities that users performed on its content.

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: ContentstackResponse. The API response with the audit log items.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
  • Throws InvalidOperationException if the instance has a UID, because FindAll lists the whole audit log. Call stack.AuditLog() with no UID.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one GET request to /audit-logs. See Get audit log in the Content Management API (CMA) reference.
  • The CMA reference states that the audit log covers the 30 days before the current day.
  • Adds the entries of collection to the query string. null or an empty collection adds none.
  • Returns the raw API response.

Example

Basic usage: list the audit log

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").AuditLog().FindAll();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: list the audit log with the branch key

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").AuditLog().FindAll(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Authentication: use a management token instead of an authtoken

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").AuditLog().FindAll();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

FindAllAsync

FindAllAsync retrieves the audit log of the stack, a record of the activities that users performed on its content, without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: Task<ContentstackResponse>. The API response with the audit log items.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
  • Throws InvalidOperationException if the instance has a UID, because FindAllAsync lists the whole audit log. Call stack.AuditLog() with no UID.
  • The SDK throws the client-side exceptions above when you call FindAllAsync, before it returns a task. An API rejection surfaces when you await the task.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Completes the task when the API responds.
  • Otherwise behaves like FindAll.

Example

Basic usage: list the audit log

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").AuditLog().FindAllAsync();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: list the audit log with the branch key

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").AuditLog().FindAllAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}