AuditLog

View as Markdown

AuditLog

The audit log records the activities in a stack, such as publishes, updates, and deletes, with who did them and when. Use this class to

  • list the audit log of a stack
  • fetch one audit log item by its UID

The auditLog method on Stack returns a new AuditLog. It has two forms:

NameTypeDescription
logItemUidStringUID of an audit log item. Omit it to read the whole log.

Additional Resource The Audit Log section of the Content Management API (CMA) reference describes both requests and their responses.

addHeader

addHeader adds one request header to the requests that this audit log object sends.

NameTypeDescription
key (required)String

Name of the request header.

Default: Not applicable
value (required)String

Value of the request header.

Default: Not applicable

Returns: AuditLog. The same audit log, for chaining.

Validation

  • There is no client-side validation. addHeader stores any key and value.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
  • A null key or value passes here. execute() then throws IllegalArgumentException on the next request.

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

Behavior

  • Client-side only. addHeader stores the header on this audit log object and makes no request.
  • Every request method on this audit log object sends every stored header.
  • stack.auditLog() copies the stack's headers into the new object. addHeader changes only this object, not the stack or other objects.
  • A second call with the same key replaces the first value, including a header the stack set, such as authorization or branch.

Example

Basic usage: read the audit log of another branch

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AuditLogOnBranch {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog()
                .addHeader("branch", "<BRANCH>");

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addHeaders

addHeaders adds several request headers at once to the requests that this audit log object sends.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

Returns: AuditLog. The same audit log, for chaining.

Validation

  • Throws NullPointerException when the map is null, because addHeaders copies its entries.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addHeaders copies every pair into the headers of this audit log object and makes no request.
  • Every request method on this audit log object sends every stored header.
  • A key that already exists takes the new value, including a header the stack set, such as authorization or branch.

Example

Basic usage: add headers from a map

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AuditLogWithHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        HashMap<String, String> headers = new HashMap<>();
        headers.put("branch", "<BRANCH>");
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog().addHeaders(headers);

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParam

addParam adds one query parameter to the requests that this audit log object sends.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter.

Default: Not applicable

Returns: AuditLog. The same audit log, for chaining.

Validation

  • There is no client-side validation. addParam stores any key and value.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
  • A null key or value passes here. execute() then throws IllegalArgumentException on a request that sends query parameters.

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

Behavior

  • Client-side only. addParam stores the pair on this audit log object and makes no request.
  • find send every stored parameter. fetch does not send them.
  • The SDK writes the value with its toString() method. Pass a JSONObject for a JSON value such as query, because its toString() returns JSON.
  • A second call with the same key replaces the first value. The parameter stays on the object for every later request until removeParam removes it.

Example

Basic usage: include branch details in the audit log

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AuditLogWithBranch {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog()
                .addParam("include_branch", true);

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParams

addParams adds several query parameters at once to the requests that this audit log object sends.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

Returns: AuditLog. The same audit log, for chaining.

Validation

  • Throws NullPointerException when the map is null, because addParams copies its entries.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addParams copies every pair into the query parameters of this audit log object and makes no request.
  • find send every stored parameter. fetch does not send them.
  • A key that already exists takes the new value. Keys that are not in the map keep their values.

Example

Basic usage: add parameters from a map

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AuditLogWithParams {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        HashMap<String, Object> params = new HashMap<>();
        params.put("include_branch", true);
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog().addParams(params);

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

fetch

fetch builds the request that retrieves one item from the audit log by its UID.

Returns: Call<ResponseBody>. The request for the audit log item, sent when you call execute().

Validation

  • Throws NullPointerException when the object has no item UID, because the request path needs one. Create the object with stack.auditLog(logItemUid).
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • One execute() sends one Get audit log item request (GET /v3/audit-logs/{log_item_uid}) with the headers on this object.
  • fetch does not send query parameters, so include_branch from addParam never reaches the API on this request.
  • The API returns audit log information for the 30 days before the current day only.
  • Read item UIDs from the uid of each item that find returns.
  • The response body is the raw JSON from the API, with the item under a log key.

Example

Basic usage: fetch one audit log item

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchAuditLogItem {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        // Pass the uid of one item from the find response as the first program argument
        String logItemUid = args[0];
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog(logItemUid);

        Response<ResponseBody> response = auditLog.fetch().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

find

find builds the request that lists the audit log of the stack.

Returns: Call<ResponseBody>. The request for the stack's audit log, sent when you call execute().

Validation

  • There is no client-side validation.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • One execute() sends one Get audit log request (GET /v3/audit-logs) with the headers and query parameters on this object.
  • The API reference lists the following two query parameters for this request. Add them with addParam:
    • include_branch: true adds the branch key to the response.
    • query: a JSON query that filters the log items.
  • The API returns audit log information for the 30 days before the current day only.
  • The response body is the raw JSON from the API, with the items under a logs array. Each item names its module, event_type, created_by, and created_at.
  • The SDK sends one request and does not page through results.

Example

Basic usage: list the audit log

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListAuditLog {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog();

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Filter the log: list only the changes to environments

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class ListEnvironmentChanges {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        JSONObject query = new JSONObject();
        query.put("module", "environment");

        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog()
                .addParam("query", query)
                .addParam("include_branch", true);

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

removeParam

removeParam removes one query parameter from this audit log object.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • There is no client-side validation. A key that the object does not hold changes nothing, and removeParam does not throw.

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

Behavior

  • Client-side only. removeParam deletes the parameter from this audit log object and makes no request.
  • Later requests from find no longer send the parameter.
  • removeParam returns nothing, so call it as its own statement, not in a chain.

Example

Basic usage: drop a parameter before the next request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class RemoveAuditLogParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        AuditLog auditLog = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").auditLog()
                .addParam("include_branch", true);
        auditLog.removeParam("include_branch");

        Response<ResponseBody> response = auditLog.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}