Track dates and users of every create or update operation. Compare versions of documents.
npm install --save fpl-mongoose-audittrail
Ownership has been transferred to MEAN Factory and is available under their mf-mongoose-audittrail package.
No updates will be made to this project. Please replace all instances with the new version from MEAN Factory.
- Add audit fields to schemas with one line of code
- Track date created, date update, or both
- Track user ID of the responsible operation
- Compare / contract version differences (coming soon)
- Designed to work with fpl-mongoose-dto plugin
- Automatically hide / show audit fields based on user rights
- Designed to work with fpl-mongoose-softdelete plugin
- Increase data integrity by retaining deleted data
- Retain historical data
- Flag objects as "deleted"
- Automatically remove deleted data from result sets
- Manually find or count data with or without deleted items
No additional coding is required besides adding the plugin to the schema. However, the defaults may be overridden to alter the functionality of the plugin. This is done by supplying a JSON object in the following hierarchy to the plugin while attaching it to the schema:
{
created : {
use : true, // set to false to disable
key : 'audit.created', // used by fpl-mongoose-dto plugin
hide : undefined, // used by fpl-mongoose-dto plugin
name : 'Created Date', // used by fpl-mongoose-dto plugin
path : 'ac', // actual path in schema
show : undefined // used by fpl-mongoose-dto plugin
},
updated : {
use : true,
key : 'audit.updated',
hide : undefined,
name : 'Updated Date',
path : 'au',
show : undefined
},
member : {
use : true,
default : undefined, // generally used while seeding your database
type : Schema.ObjectId, // override the data type or use uuid setting
key : 'audit.member',
hide : undefined,
name : 'Audit Member',
path : 'am',
show : undefined,
uuid : undefined // flags data type as UUID (uid, v1, v4)
}
}
Note:
If desired, you may use UUID values for the Audit Member ID field by setting the uuid:
property. Valid options are 'uid'
, 'v1'
, and, 'v4'
. Setting this value will automatically change the dependent parameters within the schema (type, etc.). For example:
{
member : {
uuid : 'v4'
}
}
Date Created and Date Updated are added automatically. Member ID may be added by default or passed in.
In the example below we are seeding the database. The optional (extended) Unique Identifier type is supplied along with the ID of the System Administrator user. None fo the values in the audit fields (ac
, au
, or am
) were supplied after the creation of the schema.
var mongoose = require('mongoose'),
fplAudit = require('fpl-mongoose-audittrail'),
enums = require('../enums');
var personSchema = mongoose.Schema({
s : { type: String, name: 'SSN' },
p : { type: String },
f : { type: String },
m : { type: String, name: 'Middle Name', key: 'name.middle' },
l : { type: String, name: 'Last Name', key: 'name.last' },
bm : { type: Number, name: 'Birth Month', key: 'dob.month' },
bd : { type: Number, name: 'Birth Day', key: 'dob.day' },
by : { type: Number, name: 'Birth Year', key: 'dob.year' }
});
personSchema.plugin(fplAudit, {
member: {
uuid : 'uid',
default : '40B30547A8F748EC91D57A95749E0112'
}
);
module.exports = mongoose.model('Person', personSchema);
{
s : '123-45-6789',
p : 'MR'
f : 'Joe',
m : 'Dweezil',
l : 'Blow',
bm : 12,
bd : 31,
by : 2000,
ac : Fri Aug 19 2016 15:35:23 GMT-0400 (EDT), // Date Created
au : Fri Aug 19 2016 19:14:03 GMT-0400 (EDT), // Date Modified
am : '40B30547A8F748EC91D57A95749E0112' // Responsible User ID
}
Adding the fpl-mongoose-dto plugin allows for the output of the toJSON()
call to be prepared for user-facing application usage.
Adding the fpl-mongoose-dto plugin extends the capabilities of the fpl-mongoose-audittrail plugin for a more cosmetically pleasing and human-readable presentation.
var mongoose = require('mongoose'),
fplAudit = require('fpl-mongoose-audittrail'),
fplDto = require('fpl-mongoose-dto'),
enums = require('../enums');
var GUEST = 10,
USER = 20,
OWNER = 30,
ADMIN = 40;
var personSchema = mongoose.Schema({
s : { type: String, name: 'SSN' },
p : { type: String, name: 'Prefix', enums: enums.NamePrefix.ids },
f : { type: String, name: 'First Name', key: 'name.first' },
m : { type: String, name: 'Middle Name', key: 'name.middle' },
l : { type: String, name: 'Last Name', key: 'name.last' },
bm : { type: Number, name: 'Birth Month', key: 'dob.month' },
bd : { type: Number, name: 'Birth Day', key: 'dob.day' },
by : { type: Number, name: 'Birth Year', key: 'dob.year' }
});
personSchema.plugin(fplAudit, {
created: {
hide : '< ' + USER
}
updated: {
hide : '< ' + USER
}
member: {
uuid : 'uid',
default : '40B30547A8F748EC91D57A95749E0112',
show : '>= ' + USER
}
);
personSchema.plugin(fplDto);
module.exports = mongoose.model('Person', personSchema);
var result = person.toJSON({
hide : '_id',
show : ['bd', 'by'],
level : USER
});
{
prefix : {
id : 'MR'
},
name : {
first : 'Joe',
middle : 'Dweezil'
},
dob : {
month : 12,
day : 31,
year : 2000
},
audit : {
member : '40B30547A8F748EC91D57A95749E0112'
}
}
- The Audit Fields are build out in a more human-readable hierarchy.
- Some fields are hidden by the fpl-mongoose-dto plugin because the
hide
andshow
settings passed into the plugin when it was added to the schema. - Other fields in the document were automatically hidden by the fpl-mongoose-dto plugin because of the
hide
andshow
parameters added to the schema.
Remember to set the audit.member
identifier field when seeding your database. When using the default settings, the key for this field is am:
. For example:
var seedMemberId = '49031586161143F5AB37AD809538A5CE';
module.exports = {
items: [
{
t: 'E',
i: 'support@spotless.cc',
p: [
{ k: 'name', v: 'Spotless Software LLC', am: seedMemberId }
],
am: seedMemberId
},
{
t: 'E',
i: 'fred.lackey@spotless.cc',
p: [
{ k: 'name', v: 'Fred Lackey', am: seedMemberId }
],
am: seedMemberId
}
]
};
You may also want to override the the type:
setting for the audit.member
field. The example above uses the 'uid'
identifier type, so the plugin settings for this would be:
var externalProfileSchema = new mongoose.Schema({
_id : String,
t : String,
i : String,
p : { type: [ propertySchema ] }
});
externalProfileSchema.plugin(fplAuditTrail, {
member: {
uuid: 'uid'
}
});
module.exports = mongoose.model('ExternalProfile', externalProfileSchema);
the type:
The following projects have been designed specifically to work with each other:
fpl-mongoose-audittrail (this plugin)
Track who and when documents are created and updated without complex programming. Compare and contract different versions of each document.
Convert to/from JSON DTO while applying optional level-based hiding.
Increase data integrity by retaining historical data and preventing data from being permanently deleted. Each delete
operation causes the document to be marked as "deleted" and subsequently hidden from result sets.
Provides additional validation for extended data types, field lengths, arrays, and other useful features.
MEAN Factory
support@meanfactory.com
www.MEANFactory.com
Fred Lackey
fred.lackey@gmail.com
www.fredlackey.com