Returning an entity from a custom Rules action I'm new to writing modules and back end dev. I'm trying to write a custom Rules action that takes a list and returns one item from that list to use as a relationship end point.

I've declared the rule here and got it working as far as I can extract one item from the list and put it as a message on screen:

function rules_additions_rules_action_info() {
$actions = array(
    'rules_additions_action_get_next_list_item' =&gt; array(
        'label' =&gt; t('Get next list item'),
        'group' =&gt; t('Data'),
        'parameter' =&gt; array(
            'list' =&gt; array(
                'type' =&gt; 'list',
                'label' =&gt; t('Select the current list'),
                ),
            ),
        ),
    );

return $actions;
}


And can do something like this, for example:

function rules_additions_action_get_next_list_item($list) {
    drupal_set_message(t('The item is ' . print_r($list[0], TRUE)), 'status');
}


What I want to be able to do is return that list item as an entity so at the next step in my rule set I can do "Add an item to a list" and select it in the rules UI.

I hope this makes sense.

Thanks in advance.
If you check the rules hook hook_rules_action_info docs, you'll see the provides element:


  provides: (optional) An array describing the variables the action provides to the evaluation state with the variable name as key. Each variable has to be described by a sub-array with possible attributes as described afterwards, whereas the name of a parameter needs to be a lowercase, valid PHP variable name.


Usage example from commerce_cart module:

  $actions['commerce_cart_product_add_by_sku'] = array(
    'label' =&gt; t('Add a product to the cart'),
    'parameter' =&gt; array(
      'user' =&gt; array(
        'type' =&gt; 'user',
        'label' =&gt; t('User'),
        'description' =&gt; t('Specify the user whose shopping cart order the product will be added to, typically &lt;em&gt;site:current-user&lt;/em&gt;.'),
      ),
      'sku' =&gt; array(
        'type' =&gt; 'text',
        'label' =&gt; t('Product SKU'),
        'description' =&gt; t('The SKU of the product to add to the cart.'),
      ),
      'quantity' =&gt; array(
        'type' =&gt; 'integer',
        'label' =&gt; t('Quantity'),
        'default value' =&gt; 1,
      ),
      'combine' =&gt; array(
        'type' =&gt; 'boolean',
        'label' =&gt; t('Combine similar items in the cart'),
        'description' =&gt; t('If checked, the product will be combined added to an existing similar product line item in the cart by incrementing its quantity.'),
        'default value' =&gt; TRUE,
      ),
    ),
    'group' =&gt; t('Commerce Cart'),
    'callbacks' =&gt; array(
      'execute' =&gt; 'commerce_cart_rules_product_add_by_sku',
    ),
    'provides' =&gt; array(
      'product_add_line_item' =&gt; array(
        'type' =&gt; 'commerce_line_item',
        'label' =&gt; t('Added product line item'),
      ),
    ),
  );


Note that you need to return an array from your action with the parameters named, for this example, 'product_add_line_item':

// Only return an added line item.
if ($line_item = commerce_cart_product_add_by_id($product-&gt;product_id, $quantity, $combine, $uid)) {
  return array('product_add_line_item' =&gt; $line_item);
}


So potentially you could provide as many elements as you need in your actions for further actions or rules components.