Rules integration

For additional information about rules, documentation can be found here:
http://drupal.org/node/298476

--Ben

Hey George,

One more thought I had recently: In addition to the Rules events and conditions described above, we really should have our own Rules action that implements the module's social sharing features. For instance, we may want a "Post to linked account" action that allows any Rules event to trigger a posting to any third-party account (Facebook, Twitter, etc.) that has been authenticated by the user via Janrain Engage. Using this action, for instance, the site could automatically post messages to Facebook, Twitter, and other sites (via Janrain Engage) when users:

* Earn points (Userpoints module)
* Change roles (Drupal core)
* Create a site account (Drupal core)
* Earn a badge (User Badges module)
* Make a friend (User Relationships module)
* Bookmark site content (Flag module)

Ideally, the action should have options to post to only one linked account (post just to Facebook), post to multiple specified accounts (post only to Facebook and Twitter), or else post to all linked accounts. The action would also need a text area to specify the default message text for the posting (with regular Rules tokens available for data inserted by other modules). As you can see from the examples above, this type of Rules action would really expand the possible use cases of social sharing for Drupal site builders/developers.

One alternate approach would be to actually create separate actions for each type of linked account, such as a "Post to Facebook" action and a separate "Post to Twitter" action. The advantage of this approach is that you could have different options per action that are specific to the particular account type. (Facebook, for example, could have more available posting options than Twitter.) The drawback of this approach, however, is that we would duplicate code between actions and would need to create a new rules action every time Janrain adds support for a new third-party social network. That's why I think the first approach would probably be a more elegant solution.

Cheers,
Ben

George, sounds good. I'll be testing your initial Rules integration shortly.

--Ben

Hey George,

I've just completed testing the initial Rules integration and things are looking really good.

I tested both the 'Linked account was added' and 'Linked account was deleted' actions and they both functioned well.

I also tested conditions for each of these actions and I got that working, too. Specifically, I used the generic Data Comparison condition to only take an action if a specific 'provider' had been added. That worked, too, although it took me a little while to figure out that I needed to use the human-readable version of the provider name (such as "MySpace") instead of the machine name ("myspace"). Because the data comparison needs to be an exact match, upper and lower case needs to be exact.

So one suggestion: Can you post below a list of all the possible human-readable provider names? That will be useful for anyone who wants to create a Data Comparison using the provider name. I can also add this list to the eventual module documentation. Otherwise, it's easy to mistakenly use 'google' instead of 'Google' and be confused why the data comparison isn't working.

So that we have it handy, here's a list of the provider machine names (as I found in the Janrain Engage documentation) that we need human-readable names for:

"aol"
"facebook"
"google"
"live_id"
"myspace"
"openid"
"yahoo"
"flickr"
"livejournal"
"myopenid"
"verisign"
"wordpress"
"blogger"
"hyves"
"netlog"
"twitter"
"linkedin"
"paypal"

Let me know if I left out any recently added providers.

And have you made any progress on the "Post to linked account" rules action?

Nice job on all of this! :-)

Best,
Ben

George,

Can you make both machine names and human-readible names available to Rules? Basically, there would be two different versions of 'provider' available with slightly different names to differentiate between the two.

The reason is that the human-readable versions were handy if you ever needed to use the provider name as a user-facing token within a Rules action.

For example, if your action was to 'Send a mail' or 'Show a message on the site', you could use the human-readable version of the provider name and actually have the proper capitalization when it is displayed to the user in the e-mail or screen message.

If you wanted to include the provider name in the subject line of an e-mail, for instance, you could use code like this:

Subject:  You added a linked <?php echo $rpx->provider; ?> account.

So machine names are easier to use for data comparisons (and similar user cases), but human readable versions are helpful for tokens.

--Ben

One more thing: I think we should change the Rules group for both the 'Linked account was added' and 'Linked account was deleted' events. Both are now part of the 'User' group (which does make perfect sense logically).

However, when most contributed modules add their Rules events, they usually create their own group (so that the events are easy to find in the big list of possible events). Currently, it looks like 'Linked account was added' is a Drupal core event because it is listed with all of the other core user events. So I'd recommend making these two events part of a separate "Janrain Engage" group. This would make these events very easy to spot when you first enable the Janrain Engage Rules integration sub-module (because they would be in their own separate group section).

--Ben

George,

I've done a bit more testing of the existing Rules integration and the new "provider-title" and "provider-machinename" are working well.

--Ben

P.S. Just one note for anyone who want to use "$rpx->provider-title" or "$rpx->provider-machinename" to do a replacement with PHP evaluation (or later with tokens). Because rules substitutes dashes for hyphens, you have to use "$rpx->provider_title" or $rpx->provider_machinename" to make the replacement work properly. It's an easy thing to forget and can easily cause you to wonder why it isn't working.

Hey George,

All great points and questions. A few things:

1. In thinking about it, I actually think we actually want two different Rules actions here (and possibly a third):

a) "Launch social sharing widget" -- This action would simply pop up the social sharing widget and allow the site administrator to specify the default post message (with tokens) from within the rules configuration. This would be the simplest to implement and would work for all subscribers.

b) "Automatically post to linked account" -- This would be the "slick" method you describe above for server-to-server social sharing. Yes, I think it would be important to implement some type of batching or asynchronous solution. It's fine if this only works for Pro and Enterprise users because we also provide the method in a).

c) "Load a user's linked accounts" -- This is an optional third action which would allow Rules to take subsequent actions based on which type of accounts are linked to the user. You could specify, for instance, that the subsequent "Launch social sharing widget" action would only occur if the user has a linked Twitter account. I'm not sure how difficult this would be to implement from the module code perspective.

What do you think? One suggestion for how to proceed would be to get a) working first (since it's the simplest), then work on the other stuff.

--Ben

P.S. I'll test the [rpx:provider-machinename] and [rpx:provider-title] tokens very soon and report back.

George,

Yes, the Rules module allows rules to be nested within other rules. The key is to create a "rule set" and define arguments that you need within that rule set.

Here's an example using the Private Message module (http://drupal.org/project/privatemsg): I recently configured a rule that sends a reminder email to a user when the user receives a new message and has more than 10 unread messages in his private message mailbox. To do this, I did the following:

1. Created a "rule set" by selecting "Add new component" from the "Components" tab.
2. Within this rule set, I created a "data comparison" condition (setting the data value to greater than 10) and defined a new argument to be compared named "unread-messages".
3. Also in this rule set, I created a "Send e-mail" action that sends an e-mail to the [recipient:mail] token. This e-mail will be sent if the data comparison in 2. is true.
4. Now that this rule set is created (and can be called upon later), I create a brand new rule. This rule fires on the "A message is sent" event.
5. Within this new rule, I first create a "Load number of unread messages" action (an action supplied by the Private Message module). I choose the private message "recipient" as the user account and provide a variable for the "Number of unread messages". I name this variable "unread_count".
6. I add another action to this rule. This time I choose the rule set that I previously created (which is listed as an available action in the "Components" group). As my data selector for the "unread_messages" argument (which matches the name I gave in step 2.), I choose "unread-count" (which matches the variable name I gave in step 5). For the recipient, I choose the private message "recipient" as my data selector.

Now when I send a user a private message, the rule first loads the unread messages of the recipient and then fires the rule set. The number of unread messages is available to this rule set as an input. If the number of unread messages is greater than 10, then the e-mail action is fired.

So this example illustrates how a "Load a user's linked accounts" action could potentially be used in a similar fashion. In our use case, we'd first fire the "Load a user's linked accounts" action and then use this as an input to a subsequent rule set (which would only launch the social sharing widget if the loaded linked accounts contained "twitter" as a provider-machinename).

In this way, Rules configurations can actually be quite powerful.

--Ben

One more thing: For an example of how to code the "Load a user's linked accounts" action, see the "Load number of unread messages" action supplied by the Private Message module (http://drupal.org/project/privatemsg). The Private Message module has a sub-module named privatemsg_rules.

--Ben

Also, thinking about the automatic server-to-server social sharing:
wouldn't users want to control what gets shared on their social
networks? When we pop up the widget, they at least have a choice in
the matter.

Well, there could be some use cases where you would want this done automatically (such as if you're congratulating a user on earning a badge, it's a little weird to let the user re-write their own congratulations message in the widget). But I think you're right that the "Launch social sharing widget" action would be suitable for many use cases because it allows for user approval in each instance. It's also the simplest to implement.

So perhaps we should start with the "Launch social sharing widget" action and get that working first....

--Ben

Hey George,

I just tested your tokens for [rpx:provider-machinename] and [rpx:provider-title]. It's working perfectly. I tested those tokens both with rules integration and in the verification e-mail. In both cases, everything is working as expected. Nice work! :-)

--Ben

Hey George,

I've just completed some testing of the new "Launch social sharing widget" action and it is working very well. A few things I noticed:

1) When sharing with Facebook (and possible some other networks), the page title is hard-coded into the share text. Sometimes this is undesirable because the widget may be launching from a private page that outside users don't have access to. So could we offer a field in the rules config that allows for customizing what is used as the page title? See this screenshot for an example of what I mean:

https://skitch.com/benk_tech/rs4cr/facebooktest

2) When sharing with Facebook, it is posting the first name of the Facebook user before the link text. Is there any way to get rid of this and just have the link text be the entire text (with no first name prefix)? See this screenshot for an example:

https://skitch.com/benk_tech/rs4ct/facebooktest

3) In the social sharing widget, it isn't respecting capital letters in the widget. For instance, my user name is BenK Last, but it is displaying in the widget link text as "Benk last". It will display with proper capitalization once share with Facebook, but it would be better if the widget also displayed it the proper way. See this screenshot:

https://skitch.com/benk_tech/rs4ca/widgettest

4) If an apostrophe is included in the description, it is displaying in the widget as:

'

It will look fine when eventually posted to Facebook, but it appears the text needs to be escaped before being displayed in the widget. See an example here:

https://skitch.com/benk_tech/rs4py/apostrophe

5) I've been trying to chain rules so that when a the social sharing widget is launched other actions (send a thank you message, award points, change roles, etc.) can be taken in response. But what I realize now is that in our current implementation we don't really know if the user actually shared something... we just know that they launched the sharing widget (but could have closed it without sharing). To solve this, I think there are two possible options:

a. Create a new "User shared via social widget" Rules event. By having this new event, we'd actually know that information was shared with linked accounts and could take subsequent actions. This shouldn't be any harder to implement than the original "Linked account was added" event.

b. Create two or three new Rules events:

* "User shared content" (for nodes)
* "User shared a comment" (for comments)
* "User shared other information" (for other site stuff triggered by the "Launch social sharing widget" action... specially not nodes and comments)

The advantage of this latter approach would be that for the "User shared content" event, for instance, you could easily allow conditionals for the content type so that the action would only fire if an "article" content type was shared.

So George, what do you think? I'm excited about these new possible events. It would give site builders the ability to reward users for sharing content (and would also, in turn, increase the repeat use of Janrain Engage).

Cheers,
Ben

One additional note on item 4) above (apostrophe issue): In addition to the "description" area of the widget, if the comment text includes a token (such as node title) and that token includes an apostrophe (such as a node titled "Ben's Article"), then the apostrophe in the comment area is also not being escaped properly. I'm not entirely sure if this is an issue with our module or possibly a Token issue.

--Ben

Bumping this so that I remember to test...

George,

I've been testing the three new Rules events (related to the social sharing cookie being set) and I've gotten mixed results. The "Social sharing cookie was set for shared content" is working great. But I can't get the ones for comments and other information to work properly.

A. When I try to use the "Cookie was set for comments" event, I get a "Page Not Found" error when the the event is supposed to be triggered. The error is occurring when trying to visit the following URL:

http://localhost/node/rpx/cookie_handler?destination=http://localhost/no...

Also, the above URL occurs when sharing a comment immediately after posting it. If you try to share a comment you posted previously, you get the same Page Not Found error, but the link doesn't specify the comment ID:

http://localhost/node/rpx/cookie_handler?destination=http://localhost/no...

B. I tried the "Cookie was set for other information..." event in the following setup. First, on the "Linked account was added" event, I created a "Launch social sharing widget" event. Then, on the "Cookie was set for other information..." event, I created an action to award the user points (via the Userpoints module). But even though the event evaluates true (according to my Rules debug), it does not seem to be triggering the Cookie was set event.

C. The "Cookie was set for content..." event is working nicely, but a couple of quick suggestions. First, if possible, it would be nice to have "rpx:user" available as a data selector (like we have for other Janrain Engage events). Currently, on the default current site user is available. Second, is it possible to allow a conditional for the provider that was shared with (so that the event would only fire if the cookie was set for sharing with Facebook)? We have this, for example, for the "Linked account was added" event. I'm not sure how difficult this would be to implement because the cookie would somehow need to record that information. Anyway, just an idea.

--Ben

I just tried to test the fixes to 1) and 4) from comment #27, but now I can't get the "Launch social sharing widget" action to fire. Is it working in your -dev environment? Or did we introduce a bug in a recent commit that causes this to no longer work?

--Ben

George,

Did you try the "Launch social sharing widget" with a core event? Did that work? I also tried to launch the social sharing widget on the "Linked account was added" event and that didn't work either.

--Ben

P.S. I've only tested using administrator users so I wouldn't have found the error if it only happened with non-admin users.

George,

I don't think this is a Userpoints problem (or if it is, that's an additional problem to something in the Janrain Engage module). I just tried the following:

* Rules event: After saving new content
* Rules action: Launch social sharing widget

This rule did not work for me. Can you see if it works for you?

--Ben

I've confirmed that the "Launch social sharing widget" is now working for me even when using the overlay. The only issue is that it only seems to work once the overlay is closed. For instance, if I enable the "Launch social sharing widget" action on the "After saving new content" event, then the widget launches immediately because the overlay is automatically closed by Drupal when adding new content. But if I instead use Userpoints' "User was awarded points" action--and add points using the admin-only user points add form--then the widget won't fire until the overlay is manually clicked closed.

Not sure if there is a solution for this... but it's a fairly minor issue since only those with some admin access would presumably be using the overlay.

--Ben

George, in my setup non-admin users are able to earn userpoints (from the "Grant points to user" action). So I'm not sure about the problem you were experiencing. But I'm also using the latest -dev version of Userpoints (rather than the beta) so that could be an old issue that is now fixed.

--Ben

Confirmed that 1) (hardcoded page title) and 4) (apostrophe not escaped) are both fixed. :-)

George,

I've confirmed that the following Rules events are now working:

"Social sharing cookie was set for shared content"
"Social sharing cookie was set for shared comment"
"Social sharing cookie was set for other information"

Only one strange thing I noticed that I couldn't reproduce: On two occasions when I shared content (a node), both the shared content and shared comment events fired simultaneously. I tried to recreate this but I couldn't. Most of the time everything works fine. Any reason why sharing content would also set the comment cookie in some rare circumstances?

Anyway, everything is working pretty well... just thought I'd mention this in case you had an idea as to the possible cause.

--Ben

That makes sense. Any thoughts as to my comment #56?

Marking this as fixed since most of the items on this thread have been accomplished. We can open up new thread for further Rules integration.

--Ben