The Journal Module

When more than one person is working on a site there invariably comes a moment when something breaks but nobody changed anything . . . or did they? A version control system catches the file changes, but what about Drupal settings? A new module addressing this issue appeared on the module RSS feed last month so I took a look.

The Journal module (Release 5.x-1.0) is very straightforward. It adds an additional text field named "Journal entry" to all Drupal forms via hook_form_alter.

Journal entry field screen shot

The field is mandatory for system settings forms, and non-mandatory for other forms. Some forms are excluded by the module (search_block_form, user_login_block, devel_switch_user_form), but there is no user setting to add additional forms to the exclusion list.

The journal entries are viewed at Administer >> Logs >> Journal entries. The date, user, journal entry and form's source URL (which it calls location) of each entry is displayed. These entries are stored in a database table created by the module.

Journal entry field screen shot

The Journal module has a single access permission: access journal. Only accounts holding this permission see any of the Journal module functionality. This means you can create account roles that can change system settings but do not fall under mandatory journaling (I consider this problematic, but have worked in shops that would consider this a welcome feature).

User permissions screen shot

The module also has an Administer >> Site configuration >> Journal page, but oddly there are no settings. In reviewing the module code, there actually doesn't appear to be a settings form included in the module.

For content the Journal entry field is competing with the Log message field. Although these fields are logging information for different reasons, both are capturing the same information. There will likely be annoyed users at sites wanting to use both functions.

Screen shot of Log entry field and Journal entry field

The module's stated goal is "to allow developers and site administrators to record and track all actions that have been performed to setup a site or change its configuration" [1]. From this reviewer's perspective it's off to a good start. This would be a good tool in a cooperating team. Or in my case, tracking otherwise forgotten changes on some small sites I maintain solo.

If your requirement is a mandatory audit log this module isn't it. For example, the user permissions form is not a system setting form so the journal entry is not mandatory. Given user permissions can have a dramatic effect on site functionality (e.g. A module's anonymous access is turned off breaking a feature) you'd probably want mandatory logging for it.

The Journal module project page is Newly released into the community, I'll be following its progress with interest.

[1] Journal Module 5.x-1.0 README.txt


Nice write up, Dale. I'm in the process of making a new "Raincity Base" to use for all projects, and the Journal module is an excellent candidate. I'm going to point Djun at this -- I bet he will get a kick out of automating it so that it will automatically log the previous / current value automatically, along with the actual human description.

I was thinking the same thing about automatically logging the previous and current values. Even if you require people to fill in the field, you'll get a lot of garbage, especially when people think the adjustment they're doing is not important. "Oh it's just a small change, I'll just put 'bla' in there."

Regarding the double fields "Log message" and "Journal entry": it might be a good idea to name the module "Advanced log" and to put this functionality on top of the current logging. So there is just one log type, the normal log message for nodes remains the same and a log message for each form is added.

don't forget that workflow module has its own log message field. stack up 3 and see how it looks!

nice find, this module.

I think everyone who has commented here has a similar vision. Let me sum it up and elaborate, and maybe we can build it into core for D7:

- It should be possible to centrally log all user actions
- The changes should be recorded
- Log messages should be possible everywhere
- Log messages could be made mandatory for classes of forms (such as admin config).

If we have a solid basis for this in core, we can then do site profiles that are macros =)

Thanks, Dale, for pointing me to this post! That's an excellent write-up, you've done here!

maybe we can build it into core for D7
That was the reason for choosing the generic name 'journal'. Developers might call it 'changelog', though ;)

double fields "Log message" and "Journal entry"
Correct me if I'm wrong, but the "Log message" field is only displayed if node revisions are enabled, isn't it? Although there could be some more logic for Drupal core integration, I think that site administrators/developers (target audience) know the difference and importance of both fields.

centrally log all user actions what Journal is actually doing.

changes should be recorded probably doable, but would ideally require Diff module to be installed.

Log messages should be possible everywhere a built-in feature due to the global form_alter. This was considered thoroughly, since one could have a special node containing PHP-code that might be essential for a site.

Log messages could be made mandatory for classes of forms
...would require all modules to implement this class - turning it the other way around is

we can then do site profiles that are macros
Yes, this is :) However, I'm working on Demo Site module integration currently to display available snapshots in the journal, and to create snapshots that automatically contain the current journal log.

@Dale: You might want to add blockquote to the list of allowed HTML tags. :P