What would you like to know more about?

Show Page Sections

Audit Log

What the Audit Log is and how it works, including best practices and examples.

  • The Audit Log notes changes made to a record. The Audit Log exists on every Page in MinistryPlatform.
  • To access the Audit Log, open a record and click the Audit Log panel. When the panel opens, you can click By Date or By Field to sort the Audit Log accordingly. You can further expand each Audit Log entry to see the Previous Value and New Value.
  • Dates are in the User's local time, determined by the User Timezone or the Domain Timezone if the User does not have one.
  • Audit Log reports are available to those with the Administrator Security Role.
  • If you created or updated something while impersonating another User, the Audit Log notes the actual User and the impersonated User. This occurs when an API client (for example, BMT) acts on behalf of a User (for example, to create a Donation record using the BMT) or if an administrator impersonates a User (for example, using the Impersonate User feature).
  • If you receive the "no records found" message when you create the Audit Log, the record was part of the software at implementation or added directly to the database through the back end.
  • An API User without an "on Behalf of" specified in the Audit Log means that a person created or edited the record without logging in and therefore didn't automatically match to an existing User. For example, when a person that isn't in the Platform registers for an Event, the related Event Participant record displays Created by: API User.
  • SYSTEM in the Audit Log means that the Sign-in/Sign-up flow that several Widgets and external providers use created new Contact and User records.
  • As a best practice, we recommend you create a NEW company contact and a NEW user per integration. Then, add the NEW API Client record and name it something other than _apiClient. When you do this, the Audit Log displays exactly which integration made the change. Review Giving Developers Access for more information.
  • Context is important when looking for Audit Log entries. The Audit Log tracks changes made to any field on a single record, but it can't see related changes beyond that record. For example, if you add a Participant to a Group, this does not affect the fields on either the Participant or Group record, so the changes don't display in either record's Audit Log. However, the changes display in the new Group Participant record's Audit Log.

Audit Log Retention Policies

To optimize your system's performance and storage efficiency, we implemented policies around audit log retention. These can be found under System Setup > Audit Retention Policies. (You may need to change the view to All Records to view the policies.)
  • For high-volume areas of MinistryPlatform, the Audit Log will keep changes for 90 days.
  • For other areas that don't impact system performance, the Audit Log will keep 15 years of changes.
    Tip: Don't need 15 years of change history? You can shorten it! With less to sort through, your system runs faster.

These policies do not delete any of your data, just the fact that the data was changed.

If you have concerns about the retention policy for a specific table, feel free to reach out to Support.

Why is this important?

Audit Log records build up over time and take up the majority of storage space on your system. Clearing out old audit logs frees up valuable space and makes the system run faster.

What are the high-volume areas?

The Audit Log keeps changes made to the following high-volume areas for 90 days: Messages, Recipients, Message Templates, Page Views, System Tasks, and Webhook Invocations.

How does it work?

When an audit record passes your retention period, the policy deletes it permanently. That history is gone and can't be restored.

The record that was audited stays put. The policy deletes the audit log record of a change. For example, if you change your policies to delete any Audit details for the Donations Table after seven years, then any changes recorded in the Audit Log more than seven years ago will be deleted. However, the Donations themselves are still there.

What is the current impact?

To help you see the impact that large tables have on your system, you can take a look at two views:
  • In the navigation menu, click System Setup > Audit Stats. Select the Large Audit Tables view to see row counts and approximate storage space in the Audit Log. Use this information to gain insight into what's stored in your Audit Log. There may be opportunities to reduce this by cleaning up the records in those tables.
  • In the navigation menu, click System Setup > Table Stats. Select the Large Tables view to see the percentage of space your Audit Log and Audit Details are taking up. Use this information to understand why the Retention Policies are necessary. The lower the percentage, the better your system's performance will be.

These two views tell you where your history is piling up. That's where a shorter retention period can help. You can update your retention policies at any time.

Change an Audit Log Retention Policy

The default policy is 90 days for high-volume areas of MinistryPlatform and 15 years for other areas that don't impact system performance. We don't recommend increasing these numbers, but you can lower them at any time to improve your system performance.

CAUTION: Before you shorten an existing policy, talk with the people who handle your financial or membership records. Some organizations keep longer history for their own review practices.
  1. In the navigation menu, click System Setup > Audit Retention Policies. (You may need to change the view to All Records to view the active policies in place.)
  2. Open the audit retention policy you want to change, and click Edit Record.
  3. Change the number of Audit Retention Days.
  4. Make any other necessary changes.
  5. Click Save.

Add an Audit Log Retention Policy

You can add a retention policy for other MinistryPlatform tables to improve your system performance and keep your audit log data tidy.

CAUTION: Before you add a retention policy, talk with the people who handle your financial or membership records. Some organizations keep a certain amount of history for their own review practices.
  1. In the navigation menu, click System Setup > Audit Retention Policies. (You may need to change the view to All Records to view the active policies in place.)
  2. Click New Audit Retention Policy.
  3. For Retention Type, select Erase Audit Records.
  4. Select a Table Name. Choose the specific table you want to set this policy for.
  5. Select the Audit Type the policy covers: Created, Updated, Mass Updated, or Deleted.
  6. Enter your Audit Retention Days.
  7. Use Max Audits Per Run to set how many audit records each cleanup run handles. The default is 50,000.
  8. Set Is Active to Yes.
  9. Click Save.

You can watch the results under System Setup > Audit Retention Runs. Anything that didn't finish is flagged under System Setup > Audit Retention Errors.