Last updated May 4, 2016. Created on October 5, 2011.
Edited by petednz, mpp, margyly, RogerRogers. Log in to edit this page.

By default, Rules includes a direct input and a data selection interface.

Data Selection

The data selection input method allows you to drill down into the data available to Rules, in that particular context. One important benefit from data selection is the ability to explore chained variables – for example node:author:… will show you data for a node's author, without the author's user object being explicitly loaded into Rules.

rules_data_selection.png

  • If selecting an item ending with ':' you can access data inside that object, creating chains of related data.
  • Modules like References and Entity Reference will provide connections between entities, such as user:field_node_reference:nid.
  • If you are expected to provide data of a certain type, the data selector will only list data end points matching these requirements. For example, if you are using an action to set a node title, Rules will only accept data of the type 'text'.






Direct Input

The direct input mode is most useful when entering a new text token, rather than another available data variable. You can use all chains of data found with the data selector as tokens in direct input mode. For example, you can use [user:field_node_reference:nid] as a token representing the node ID of a referenced node.

rules_direct_input.png














Additional info

Rules uses an incredibly extensible plugin system to support multiple types of data input interfaces. You can read more about this API and how to add additional data selection interfaces in the developer documentation section on data types.

Lists and items within them are also types of data which can be selected.

Selection of custom fields

For entities with custom fields, you must first create a condition that sets the entity bundle type, this will allow Rules to determine the fields available for the bundle, which can then be used for comparison, etc.

To do this, add a first condition to your rule as follows:

  1. From the 'Select the condition to add' input, select Entities > Entity is of bundle.
  2. Press Continue
  3. From the 'Data selector' input select the entity you are targeting (don't use the entity with the colon, e.g. Person, not Person:).
  4. Press Continue.
  5. You should now see a new 'Entity Bundle' fieldset, select the bundle name that you want to compare field values from.
  6. Press Save.

Now you can add additional conditional rules that have access to all of the custom fields belonging to the bundle you referenced in step 5.

NB The field type you created needs to match the field type that is expected, otherwise it will not show in the selector, eg if you have a Date field, but the entity is expecting a text field!

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

Comments

earwax’s picture

Entity fields will only be available if you have used a condition to expose them ...

Huh? That entire paragraph confuses me. What am I exposing? Why am I seeing incomplete "stuff"? For example, node:field-Myfield:. It just ends with a colon (:). And then there's the node:field-Myfield. What's the difference between node:field-Myfield and node:field-Myfield:?

Itangalo’s picture

I added a clarifying example at the line starting with "If you are expected to provide data of a certain type, the data selector will only list data end points matching these requirements." I hope this helps!

TheoRichel’s picture

This manual - and the same can be said for the Nodeone video - assume that just the mentioning of something called 'Data value' is enough to let everyone know what should be put there. So far all my selections drilling down have led to 'invalid' remarks, which is no wonder because I simply do not know what I am looking for. Where is the selected data value used? what are the criteria for the correct selection? Or at least refer me to someplace where this is explained.

AlfTheCat’s picture

I agree. Rules has now become a huge pain to use. Even the simplest rule is impossible to create. I'm trying to make a rule where I'm notifiied of a comments placed on the site by anonymous users. So I can select the role "anonymous" as a condition but I still have to specify a data selector. No matter what I try user, user:, user:role, everything is invalid. I don't even know why I would have to specify this, and what it is I should specify or where I can find any documentation.

It's so sad.

----
"People make mistakes. To really mess something up you need a computer."

mttjn’s picture

Same here. Did you work this out for your use case?
I've a huge respect for the coders of this module, but this aspect is confusing me.

stellarvisions’s picture

I was struggling with this also and then found that it's best to set all that up under actions, then simply call upon the action in the rule. Much simpler.

---
Stella Gassaway
principal

stellarvisions : communication architects
http://www.stellarvisions.com

We design culture-driven tools™
that shape how information is
organized, displayed, shared, and
experienced.

escoles’s picture

Not sure what you mean by that. Are you saying there's someplace you can define actions such that they are independent of a rule?

jordan8037310’s picture

Is anyone from the Rules team going to update this with instructions that will actually help? Data Selectors are awfully obfuscated, and there is no clear indication of what information can be loaded from pre-loading a specific condition. Half the time I load a condition expecting access to some entity info, and all I get is site and user information in the drill-down. What gives?

pribeh’s picture

I'm lost as well here.

timqallen’s picture

+1

pzo3xic’s picture

Hi. I would love to charge user points for some action but when I add entity has field and then try to put this field into selectors value, I cannot add "-" before the field because it says it is not valid integer then. How can I make it negative?

Anonymous’s picture

This description was nothing but confusing. I'm totally lost here. How do I use Data selector?

sonicthoughts’s picture

I can add to the list of those confused and desperately searching for guidance on data selectors and entities. If someone does find a good description, please post here. Seems like a lot of people use php to avoid problems, but that sort of breaks the wonderful work the rules team has done in abstracting for system builders!

RogerRogers’s picture

For anyone struggling with understanding how to gain access to custom fields, particularly for custom entities, please see the updated content on this page - the last paragraph in particular. I hope this helps!

PuPhPyTaLez’s picture

Agreed. This page helps a lot. The last paragraph seems to refer to a top Condition statement but adding an "if" condition using the Conditional Rules module as "If: Entity is of bundle" also works for comparing and manipulating fields inside the bundle in the subsequent Action lines.

The problem was confusing because when choosing "Create a new entity" it is in fact possible to set the custom fields on the new entity. The difficulty only seems to arise when you "Fetch entity by property" or "Fetch entity by id". This may be a labeling or language issue. But apparently fetched entities are not full objects. And the "If: Entity is of bundle" actually instantiates the full object.

drm’s picture

How about some examples.

Anonymous’s picture

Yes, examples could be useful. Something the Drupal Community needs to learn more. Way to much tech talk and to few screenshots and real examples. That goes for ALL modules and not just this one.

webpotato’s picture

First off I have to agree with pennyc and others that too many times Drupal documentation is completely unintelligible-- and this is a situation that is getting worse and making me (and no doubt others) question how much longer I can put up with this system that seems to be fraying at the edges. Documentation, if it is to be useful to system admins (people who use the system to build websites as opposed to people who build the system), the documentation writers need to take the time and develop the skill to describe things as if the person reading it is unfamiliar with the subject.

My problem is with the Rules UI when it comes to the data selection input fields: Following these instructions, I added a condition in the hopes of exposing choices in the data selection drop-down (as shown your first screenshot example, above, rules_data_selection.png). When I click on the down-arrow, nothing happens. When I click a few times in the input field itself, blue HTML appears with div tags as shown in this screen capture:

http://s-m-a-c.org/sites/default/files/images/capture1.jpg

Clicking on the HTML does result in the entering of a value (e.g. account: or account:roles:), but I'm not seeing very many choices as are shown the example.

I'm also not seeing the button to switch to direct input.

Furthermore, it appears that the second down-arrow next to where it says "Data Selectors" (plural) should expand, but it does not for me.

In my case, I want to do something that should be a relatively simple task: When a new Drupal User signs up, add the user to the CiviCRM group called "Colleagues." In my screenshot, you can see that it is telling me to "Select data of the type Contact," but there are no contact data types listed by either of the drop-downs or the errant HTML, so I'm stuck.

Is this a bug? I have tried using different JQuery versions with no difference. I tried it in Firefox and Google Chrome.

Edit (11-18-2014): So, I just found another, seemingly related issue: I went to integrate CiviCRM Events into Drupal Rules and then when editing a new rule, this is how the new integrated fields look (showing HTML tags, see screenshot, below). Very strange.

http://s-m-a-c.org/sites/default/files/images/capture2.jpg

ron_s’s picture

It probably should be mentioned on this page that data selectors conflict with the jQuery Update module. This is the same issue that the Path Breadcrumbs module has (read more here: https://www.drupal.org/node/2066223).

If you're running the jQuery Update module, make sure to disable it first before creating Rules. Once you're done with Rules, you can re-enable jQuery Update.

UPDATE: there is also a patch that can be applied for Rules to support JQuery versions greater than 1.7: https://www.drupal.org/node/1810656#comment-8010431

myron_s’s picture

I want to see the user names people attempt that are not valid. I got the rule to work but the output does not work.

I am using:
Log message: [watchdog-message:value]

I get:
log message: Login attempt failed for %user.

Clearly this is wrong. If the Invalid user-name used is NotAValidUser then what I should get is:
log message: Login attempt failed for NotAValidUser.

Anyone know what I'm doing wrong?

TheOptimizer’s picture

How can we select keys of allowed values of fields?

Imagine you have a field with following allowed values:
a|Case A
b|Case B

Then I want to get the key, not the value. I want a, not Case A

phponwebsites’s picture

I want to change log message of particluar rules.
Is it possible? If yes, then what is the way?

Rajender Rajan’s picture

I want to add action for a event "After Saving New Content" and i want to send email to all user having some particular role but could't understand what Data selector has to use for "Subject" ?

philchen’s picture

Event:
select "Node after saving new content" and you can select any type that you define under "Restricted by type" drop down

Conditions:
Data selector: site:current-user
Role: select any role that you wany
Match roles: Any

Actions:
Send Email and configure anything that you want in the body

Hope that helps :)

Ajascosoft’s picture

I have three content types. First content type just registers cars with unique registration numbers which is published by default.
The second content type is a requisition request for a vehicle (User fills a form to request to use a vehicle). This request goes to a moderator who approves it by posting a new content type ("Approve requisition" with a node reference from the requisition request). The "Approve requisition" content type assigns a driver and a vehicle to the referenced request. Vehicle and driver are referenced entities from views.
Now, i intend to use Rules to unpublish a vehicle once it is assigned to a vehicle requisition in "Approve requisition" and also update a field on the assigned driver's profile.
I have been going through this use-case with Rules for the past few days.
Any help will be very much appreciated. I am new to Rules.

philchen’s picture

You should be able to set a rule to listen the "Approve requisition" action. Please give a bit more detail on what your issues are if you have not find the answer.

siddhu151plex’s picture

I want to send an email by rules using Check number of results returned by a VBO view condition.
I have an User:UID argument need to use.
But I can't find the User:UID in the data selector.
I have tried all available options provided in this page but nothing worked.
All I can see data belong to Site:Current-User which retrieves data of currently logged in user.
Could you provide more description on this case as an example?

s_chandela’s picture

Hello folks,
I want to send email once webform has submitted => This thing has been done.
Now if webform status (status is webform component ) has changed from Pending to Confirmed then also an email should be send to particular user ( user id is webform component ).
Now if webform status has changed from Pending to Cancelled then also an email should be send to particular user (whose id is in webform submission record).

I'm using webform 3.0 and Rules.

dan.mantyla’s picture

you'll need the Webform Rules module

jeromewiley’s picture

1. Did the people above that were confused / lost as to how to implement Data Selectors ... did they just give up? Did they find better documentation and neglect to update this page?
2. Documentation seems to be hit or miss for different Drupal modules, functions and capabilities. I understand that not everyone has the time to invest in improving the documentation, but it's something that will help everyone, as it will allow the overall quality of the Drupal community and product to really shine.
3. At first review, I'm also lost, confused, unable to make heads or tails of the information on this page. I'll continue to look elsewhere, try a number of things with the code, and if am able to figure out how it works, I'll try to write up some more "helper paragraphs" and / or examples for this section of the Documentation, as well as the section dealing with creating new Conditions for Rules.

In case anyone senior does review these pages occasionally, what I'm specifically trying to do is to build a simple module that looks up the count of a particular string ($string1) in a DB table and then makes that available to a new condition so that I can determine "Is ($logged-in-user->string1 > 0), yes or no?"

Previous commenters that expressed frustrations re: level of documentation: TheoRichel, AlfTheCat, mttjn, jordan8037310, pribeh, sonicthoughts and entendu.

Road Kill’s picture

Hi jeromewiley I completely agree with you and understand you frustration. All of us are at this page because we have questions that need answers. The Rules queue is completely congested like so many other modules with people asking for support. If better documentation was put together this would reduce many of the issue in the queue. Many of these questions go unanswered by maintainers because of lack of manpower and the large volume of issues open with some going back 3years which have still not been answered. I think what should be happening here is that more experienced users of the Rules module should be making an effort to give back to Drupal for the benefit of this amazing open source CMS.

This however is not happening which I think is why many people abandon Drupal and move to Wordpress. There are too many issue where people have solved the problem but are too lazy to post a clear step by step process of how they solved the problem. So if you solve it share it and dumb it down for those who are new to Drupal.

I have been very busy over the last 12 months but one of my goals for 2016 is to setup a website that provides comprehensive Drupal video tutorials covering all of the most used modules in Drupal to assist the lost and confused.

The goal of this project will be to:

1.Provide Drupal video tutorials that are easy for anybody to understand.

2.Help reduce support requests in the issue queues for module maintainers.

3.Help grow Drupal popularity by making more support resources available that are actually helpful.

Once i have the project up and running I will be looking for developers who want to take part in the project by creating their own videos and sharing their experience and knowledge.

I know this has been done before over and over but many of these resources are for Drupal 6 or are outdated because modules have changed after updates. This will also be a community effort were people can give back to Drupal by creating Video tutorials and sharing knowledge and experience.

Watch this space I will post a link once I have the project up and running.

mandavya’s picture

Hoping for this to happen. Will add my part as it is made

dunx’s picture

With this being the obvious page to start from as it's mentioned in the Rules UI and the majority of comments being "I still don't understand, I need more documentation", I thought I'd put my own worked example down in the hope that it would help others. It's a sub page at https://www.drupal.org/node/2796371