Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Introduction
This is the documentation for http://www.drupal.org/project/update_rules.
This module provides rules events, actions, and conditions related to Drupal project update statuses. Drupal core offers a simple email notification when the site needs core/module updates. Unfortunately those emails do not contain any information about the projects or the releases, and you're at the mercy of the standard update notification configuration. This module solves this problem, and gives you all of the capabilities (actions, conditions, etc.) of Rules for handling update statuses. Imagine being able to send an email to your task management app with the server name, project name, and release info every time a security update is needed. This is a simple example, but was the exact goal I was shooting for when I wrote this module.
If you're using update_rules to have a rule that sends emails, please make sure Rules is able to "send mail" successfully before assuming there's a problem with update_rules.
When are the rules events invoked?
This module currently triggers Rules events when the core Update module runs its update checks. Normally this happens on cron runs, visiting the Reports pages, and by other means (e.g., drush pm-update).
IMPORTANT: Visiting the Status Report page seems is the most reliable way to execute update_rules-based Rules, so I recommend using that for testing. If you're using the "Only process this release once" feature (more on this later), don't forget to delete the associated variable if you need to test your rules repeatedly.
Some of the "Available updates" settings at Admin > Reports > Available updates > Settings do apply to update_rules. The settings for "Check for updates" (frequency - daily or weekly) and "Check for updates of disabled modules and themes" do affect how often update data is refreshed and which projects are included in the checks, respectively. The email settings do not affect update_rules.
Regardless of what you use for a frequency, the update_rules events will be invoked by all of the items mentioned above (cron, status page, etc.).
Read improvements below for more info.
Terminology
Group Identifier
The only non-standard terminology used in this module is "Group Identifier." Simply put, a group identifier is a way of keeping track of update statuses separately for different rules. This is important when it comes to the "Release has already been processed" condition, because it gives you a way of keeping track of which updates your rule has already processed. I could have automatically stored the update statuses based on the identifier of the rule being executed, but I wanted to be able to let rules share "already processed" information. I've hardcoded a limit of five group identifiers. Chances are good you will only use one.
guid
There is also a "guid" value available to your conditions and actions. This value is a unique identifier for the specific project+release. I've added this so that you can keep track of releases without having to explicitly share the name of the site, project, release, etc.
If you look back at my original goal, I wanted to send an email for each security update into my task management system. This system allows duplicates, but of course I'd rather not have a duplicate task created each time cron runs. I could use the "Only process this release once" but what if the email doesn't go out the first time; it'll never make it to my task management system and I may never realize the update is needed. What I'd like to do is check if the task already exists, but I'd rather not make public the fact that site X needs module Y security updates. I am comfortable, however, making a public URL that returns true/false for whether some guid (e.g.,4dc384ba-9df1-4d65-b594-5836498005ce) exists in the task list.
I was able to get this working pretty easily:
- In my "Send mail" action I include the guid in the body (so that my task manager has the guid values for each update).
- I created a public URL in my task management system that returns a 1 if the guid (passed as "guid" GET parameter) is found in the body of a task. It returns a 0 if it's not found. Of course I made sure to santize the GET parameter and to only ever return 0 or 1.
- I added an "Execute custom PHP code" condition to the rule that returns (negated) the results of a file_get_contents() on the URL. Here's what that looks like (leave out the php tags!):
// guid already in task manager? // Condition must be negated; if guid already exists, condition needs to be FALSE to prevent sending duplicate tasks. return file_get_contents('https://mysite.com/guidalreadyexists.php?guid=' . $guid);
Hopefully this makes sense. Feel free to use the guid however you see fit, of course!
Installation
Install the module as you would any other module. After you enable it, it's up to you to create rules that use the events, conditions, and actions that update_rules provides. Please see USAGE section below to learn more.
Usage (example)
Event
You may create as many "Update Rules" rules as you want. For this example, I'll describe how to create a rule that will send an email with information about a project when a security (and only security) update is needed. (Note: if the email fails to send, you may never hear about the update; see my note above about "guid")
This module offers two events. For this example, I'll be using the second:
- After checking a project's update status (not recommended)
- After detecting that a project is not current (recommended, more efficient)
Begin by creating a new rule with the chosen event. I'm calling mine "Send email once per security update"
Conditions
The first thing to add is the "Release has already been processed" condition. We actually want to NEGATE that condition so that we only execute actions if the project release (e.g., webform-7.x-3.24) has not been processed yet. We're going to use "1" as the group identifier. We'll declare the same group identifier in one of our actions below.
The next step is to add another condition to check the type of update/release we've detected. There are several variables provided by this module, for use in your rules conditions. We can use a "Data comparison" condition to check if the "status" value is UPDATE_NOT_SECURE. The status types appear in a dropdown so it's easy to target whichever status(es) you want. If you use "equals" it'll let you choose a single status type. If you choose "is one of" it'll let you choose multiple status types. Don't forget you may also negate the condition.
Actions
Now that we are acting on security updates that haven't already been processed, it's time to do something with each update detected. We want to do two things: send an email, and make sure we only process this particular release once.
If you've used Rules, you've probably sent an email with rules. This is all standard, with the addition of having some of the project/release information available as tokens. Just add a "Send mail" action and configure as needed.
Next, be sure to add the "Only process this release once (must use with "Release has already been processed" condition. This will update the database variable that stores the "already updated" status for this project in a specific group identifier. We'll use the same "1" group identifier.
You can test your rule by running cron, using "drush up", or visiting the status report or Modules > Update admin page.
This was just one usage example. Don't be afraid to get creative with conditions and actions. Be sure to look through all of the variables available to your conditions and actions.
Additional configuration / Cleanup
To remove the "already checked" status of a group of releases (only applicable if you used the "Only process this release once" action) you can safely delete (via drush, mysql, or variable_del()) "update_rules_already_processed_N" variables from your "variable" database table. You may need to clear the Drupal cache afterwards.
For example: variable_del('update_rules_already_processed_1');
Improvements
The rules events are triggered whenever the standard Drupal update checks happen. I'd like to set this module up with its own (separate) checking routine so that it can be scheduled (via cron) as little or often as needed.
Let me know (via the project's issue queue) if you'd like me to make any other variables available to the actions/conditions.
