loopback-auditz

    0.5.0 • Public • Published

    loopback-auditz

    Travis CI Build Status NPM version NPM downloads Coverage Status Dependency Status Dev Dependency Status

    Description

    This module is designed for the Strongloop Loopback framework. It provides extensive support for Audit Trails in your LoopBack based application.

    It consists of a group of functionalities:

    Each of these main functionalities can be turned off individually.

    Install

      npm install --save loopback-component-remote-ctx loopback-auditz

    Server Config

    Add the mixins property to your server/model-config.json:

    {
      "_meta": {
        "sources": [
          "loopback/common/models",
          "loopback/server/models",
          "../common/models",
          "./models"
        ],
        "mixins": [
          "loopback/common/mixins",
          "../node_modules/loopback-auditz",
          "../common/mixins"
        ]
      }
    }

    Make sure you enable authentication by putting the following in a boot script (ie server/boot/authentication.js):

    'use strict';
    module.exports = function enableAuthentication(server) {
      // enable authentication
      server.enableAuth();
    };

    Enable the loopback-component-remote-ctx by adding the following in your server/component-config.json:

      "loopback-component-remote-ctx"{
        "enabled": true,
        "argName": "remoteCtx",
        "blackList": ["User"]
      }

    And finally use the loopback token middleware by adding the following line to your server/server.js:

    app.use(loopback.token());

    Configure

    To use with your Models add the mixins attribute to the definition object of your model config.

      {
        "name": "Widget",
        "properties": {
          "name": {
            "type": "string",
          },
        },
        "mixins": {
          "Auditz" : true,
        },
      },

    There are a number of configurable options to the mixin:

      "mixins"{
        "Auditz": {
          "createdAt": "created_at",
          "updatedAt": "updated_at",
          "deletedAt": "deleted_at",
          "createdBy": "created_by",
          "updatedBy": "updated_by",
          "deletedBy": "deleted_by",
          "softDelete": true,
          "unknownUser": 0,
          "remoteCtx": "remoteCtx",
          "scrub": true,
          "required": false,
          "validateUpsert": true,
          "silenceWarnings": false,
          "revisions": {
            "name": "other_revisions_table",
            "idType": "Number",
            "dataSource": "db",
            "autoUpdate": false
          }
         },
      },

    createdAt

    This allows you to define an alternative name for the createdAt field. When set to false, this property will not be defined nor used.

    updatedAt

    This allows you to define an alternative name for the updatedAt field. When set to false, this property will not be defined nor used.

    deletedAt

    This allows you to define an alternative name for the deletedAt field. If you don't want the soft delete functionality, specify 'softDelete': false in the options.

    createdBy

    This allows you to define an alternative name for the createdBy field. When set to false, this property will not be defined nor used.

    updatedBy

    This allows you to define an alternative name for the updatedBy field. When set to false, this property will not be defined nor used.

    deletedBy

    This allows you to define an alternative name for the deletedBy field.If you don't want the soft delete functionality, specify 'softDelete': false in the options.

    softDelete

    By default, soft delete functionality is turned on and uses the deletedAt and deletedBy configuration options. If you set softDelete to false, it completely ignores deletedAt, deletedBy and scrub, and all deletes will become hard deletes.

    unknownUser

    This allows you to define which userId should be filled out when no current user can be determined

    remoteCtx

    The value you provided in component-config.json for argName of loopback-component-remote-ctx

    scrub

    If true, this sets all but the "id" fields to null. If an array, it will only scrub properties with those names. However, if you specified softDelete: false this option will be ignored.

    required

    This defines the requiredness of the createdAt and updatedAt fields. The deletedAt field is never required

    validateUpsert

    This defines whether or not the validateUpsert property is set for the model

    silenceWarnings

    This defines if the warnings should be suppressed or not

    revisions

    If set to false, this disables keeping track of changes in a revisions model. If it's true or an object, keeping track of changes in a revisions model is enabled, and the following configuration options are availabe if it's an object:

    name

    The name for the revisions model in which to keep changes to the model.

    idType

    The data type to assume for id fields. The default is 'Number', which is fine for most databases, but (for example) MongoDB uses strings, so in that case provide "String" as the value for idType.

    dataSource

    The dataSource to connect the revisions model to. This dataSource needs to be defined in datasources.json first.

    autoUpdate

    If set to false, it will assume the model exists in the dataSource already, and we don't need to create or alter the table. If set to true, it will run autoupdate on the dataSource for the given revisions model name to make sure the table exists with the right columns.

    Usage with MongoDB

    In case you use MongoDB with this module, and also use the 'revisions' table option, you need to configure the idType as a 'String'. Otherwise this module will attempt to store the non-numeric id in the row_id property of the revisions model, which is a Number by default.

    Operation Options

    Skipping updatedAt updating

    By passing in additional options to an update or save operation you can control when this mixin updates the updatedAt field.
    The passing true to the option skipUpdatedAt will skip updating the updatedAt field.

    In this example we assume a book object with the id of 2 already exists. Normally running this operation would change the updatedAt field to a new value.

    Book.updateOrCreate({name: 'New name', id: 2}, {skipUpdatedAt: true}, function(err, book) {
      // book.updatedAt will not have changed
    });

    Retrieving soft deleted entities

    Unless you specified softDelete to be turned off, you can run queries that include deleted items in the response, by adding { deleted: true } to the query object (at the same level as where, include etc).

    Contribute

    Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

    License

    Unless stated otherwise all works are:

    and licensed under:

    Install

    npm i loopback-auditz

    DownloadsWeekly Downloads

    6

    Version

    0.5.0

    License

    ISC

    Last publish

    Collaborators

    • jouke