Last updated February 8, 2013. Created on September 8, 2010.
Edited by eosrei, gollyg, mradcliffe, drupalshrek. Log in to edit this page.

Supported data types

The list of data types supported is:

  • date
  • duration
  • integer
  • decimal
  • text
  • token
  • boolean
  • uri
  • list
  • entity
  • struct

Non-entity data structures & Entities

Any Drupal module can integrate with Rules by providing new entity types and entity metadata by using the Entity API to describe entity properties or directly by using non-entity data structures. Rules core builds heavily on the data types provided by the Entity API, however it is possible to add support for data structures which are not entities.

Additional data types are registered using hook_rules_data_info(), similar to the definition of "entity" type. This allows Rules to work with variables contained by any data or entity type and integrate at the most direct level. With this hook, you may also define the 'parent' type of a data type, that Rules makes use of for type-matching only. E.g. this is used to make it possible to apply an action working with an "entity" parameter to a node variable. However these data types are not available in Direct Input mode.

The example below uses Rules without Entity API to provide support for watchdog log entries. Property metadata needs to be specified, and a direct input form may be specified.

/**
 * Implements hook_rules_data_info() on behalf of the system module.
 * @see rules_core_modules()
 */
function rules_system_data_info() {
  return array(
    'log_entry' => array(
      'label' => t('watchdog log entry'),
      'wrap' => TRUE,
      'property info' => _rules_system_watchdog_log_entry_info(),
    ),
  );
}

/**
 * Defines property info for watchdog log entries, used by the log entry data
 * type to provide an useful metadata wrapper.
 */
function _rules_system_watchdog_log_entry_info() {
  return array(
    'type' => array(
      'type' => 'text',
      'label' => t('The category to which this message belongs'),
    ),
    'message' => array(
      'type' => 'text',
      'label' => t('Log message'),
      'getter callback' => 'rules_system_log_get_message',
      'sanitized' => TRUE,
    ),
    'severity' => array(
      'type' => 'integer',
      'label' => t('Severity'),
      'options list' => 'watchdog_severity_levels',
    ),
    'request_uri' => array(
      'type' => 'uri',
      'label' => t('Request uri'),
    ),
    'link' => array(
      'type' => 'text',
      'label' => t('An associated, HTML formatted link'),
    ),
  );
}

Token replacement in Rules is handled by token_generate(). To make additional data type properties available for replacement in Rules Actions, you must implement hook_tokens(). Here is an example:

/**
 * Implements hook_tokens().
 */
function mydata_tokens($type, $tokens, array $data = array(), array $options = array()) {
  if ($type == 'mydata') {
    if(isset($data['mydata'])) {
      $replacements = array();
      $mydata = $data['mydata'];
      foreach ($tokens as $name => $original) {
        switch ($name) {
          case 'name':
            $replacements[$original] = $mydata['name'];
            break;
          case 'address':
            $replacements[$original] = $mydata['address'];
            break;
        }
      }
      return $replacements;
    }
  }
}

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

GlitchFreak’s picture

What type of object is a rules list?

Is it a stock standard array?

If so, how would you add items to it via PHP?

Thanks

tinker’s picture

A list can contain most is not all standard data types as well as entities. When specifying the type in rules actions use list<data_type> for simple data it could be list<integer> or list<text>. Use the "options list" variable to specify a callback function that will populate the list. Depending on the entities defined you can use more complex lists such as list<taxonomy_term>.

function example_rules_action_info() {
  return array(
    'label' => t('Do something with role(s)'),
    'group' => t('Example module'),
    'parameter' => array(
      'roles' => array(
        'type' => 'list',
        'label' => t('Roles'),
        'description' => t('Select the roles to modify. Hold [Ctrl] to select multiple roles.'),
        'options list' => 'entity_metadata_user_roles',
      ),
    ),
  );
}
// Where entity_metadata_user_roles() provides a list keyed by role id integer.
kitserve’s picture

I'm having trouble passing a programmatically generated list to any other actions. I've defined an action that provides an array of User objects. When I add a loop in the Rules UI it suggests 'user-list' as the parameter to iterate over and everything looks fine, yet when I run the Rule I get errors like this:
"Unable to get variable user_list, it is not defined."

Can anyone shed any light on this?

/**
 * Implements hook_rules_action_info
 */
function mymodule_rules_action_info()
{
	return array(
		'mymodule_get_users' => array(
			'label' => t( 'Get a list of users to iterate over' ),
			'group' => t( 'Custom' ),
			'provides' => array(
				'user_list' => array(
					'label' => 'User list',
					'type' => 'list<user>',
				),
			),
		),
	);
}

/**
 *
 */
function mymodule_get_users()
{
	/*
         * <logic to get array of relevant UIDs goes here>
         */
	$members = user_load_multiple( $uids );
        // user_load_multiple indexes by UID which might be confusing the Rules loop. Reindex!
	$members = array_values( $members );
        dpm( $members ); // This works!
	return $members;
}
netw3rker’s picture

List data types don't extend the master 'list' data type (meaning 'list<user>' can't be used in place of 'list'. This is probably a bug though. My bet is that if you create a function to correct this and set the parent correctly, this problem will resolve itself for you. Here's what to try:

// this is a hook, so be sure to rename 'EXAMPLE' to the name of your module.
function EXAMPLE_rules_data_info_alter(&$data_items) {
  $data_items['list<user>']['parent'] = 'list';
}

clear your caches and see what happens.