Hook for membership status calc

[Eileen]

I have had another request for different membership statuses by membership type. We've somewhat looked at getting this into core before but it seemed ' a bit hard'. I'm now wondering if we might be able to do it by hook & by crook (well an extension).

Basically I'm thinking we might be able to add hooks to the membership status functions

The functions on the membership status class are
- Crud functions create, add, retrieve, delete
- setIsActive - variant of create which would bypass hooks but there are none
- getMembershipStatusCurrent - called from one place (dashboard), basically duplicates retrieve with a param passed in
- getMembershipStatus - duplicate of retrieve


Which pretty much means the only function of any significance is

getMembershipStatusByDate

- which is used to calculate the membership status when saving and when updating memberships by cron

Checking membershipType for any more relevant functions I find that

getRenewalDatesForMembershipType determines renewability by calling
CRM_Member_BAO_MembershipStatus::getMembershipStatus


& in membership BAO
getContactMembership & getValues do the same thing - but bypass getMembershipStatus  with CRM_Core_DAO::getFieldValue()
(could be refactored to call it)

getMembershipStarts - this is called by the member dashboard & looks to the membership_status definition rather than the membership record. I think we could eliminate a left join here & read off the membership.status_id field

getStatusANDTypeValues is called by retrieve which in turn is called from a single place in the code CRM_Member_BAO_Membership::preProcess which does not make use of the 'active' field derived from the retrieve call.


So have 2 things
1) we want to calculate the status a membership should have based on type, dates, status (basically features of the membership)
2) we want to calculate whether a given status should be treated as 'current' or not.

In the case I have I am simply wishing to apply 'grace' for a longer period for some membership types than others (#1) and it seems to me that only one place in the above code is relevant to that - getMembershipStatusByDate  - so I believe that adding a hook 'alterCalculatedMembershipStatus' & maybe increasing the params passed into this function to include membership & type details where available - would allow me to implement memberships by type using a hook.

Having statuses given different 'is_current' treatment according to various factors (e.g. membership type) would require a greater amount of refactoring - but I'm not sure I have a use case for that.

[Eileen]

I guess the alternative would be to run a 'pre' hook that sets 'is_over-ride' on all memberships of x, y. z type & then create my own job to update those in the extension. This feels clumsier to me as I am effectively creating my own membership management system rather than tweaking Civi's (& I don't know that I fully understand how is override would work in online renewals) - but perhaps I am wrong?

[andrewhunt]

This doesn't help for the perspective of customization, but re: getting it into core, maybe it would be as simple as adding a limitation field for membership types (much like custom data groups).  The default would be all, but you could have something available for only one or two types.

If that was set up, you could create a "Business member grace" that is only valid for business members and extends for longer than the regular grace and has a lower weight.  For business members, they'd hit "business member grace" ahead of grace or expired when walking through the statuses, so even though grace would be vaild for all types, let's say, business members would never hit it--once the business member grace period ran out, they'd fall all the way to expired.  (Or, in the case of a few of our clients, that status might have no end date because they'd prefer to manually expire the business members.)

Now looking technically: getMembershipStatusByDate would need a membership type ID argument, but I just checked, and everywhere that it's called, the membership type ID is readily available.  There's that query of statuses ordered by weight, and it could just filter so that the membership types field is null or contains the membership type ID.  (Or if it would make more sense for caching, run the big query with everything and then handle the status when walking through the statuses.)  I think that would be it--possibly with some sort of caveat in the edit status form when you set the statuses that if you remove a membership type from the valid statuses, you won't yank the status immediately from everyone's membership.

Anyway, I wonder whether this might be easier than doing it as an extension.  Let me know if I'm missing something big that makes it "a bit hard".  It would be broadly useful, I think.

[Eileen]

From a db point of view I don't think it would be tricky to do in Core. The main reason it would be easier to do as an extension is to save having to build a UI for it.

Fixing up the calls to getMembershipStatusByDate to pass membership type (& adding the hook) would at least make it easier to do as a UI later. I won't be providing a UI for this customer at this stage - it will be hard-coded

[Eileen]

Hi Andrew,

I've logged this & added a link to the patch I am trialling - https://issues.civicrm.org/jira/browse/CRM-14399

- would be great if you could take a look

Note that I don't have a specific use for passing our $membership - it just seems like the sort of thing you would want to be able to access from a hook. Since there is a bit of variation in what is available in calling functions I have cast to an array.

[andrewhunt]

I looked through this, and it looks great.  I agree about sending $membership through as an array.  The only thought is that if you're doing that, do you need the status ID as its own param?  Argument against is solely that it's redundant.  Argument for is that passing the membership params through as a whole might be missed somehow, though I don't know why.  (Perhaps if you've got some situation where you'd want to display on a form what a status would be if you were to renew, but then again, you could really just pass "array('membership_type_id' => 4)" or something.  The only real use case for that is an organization that forces members to pay for years of lapsed membership in order to rejoin.)

[Eileen]

hmm - I think the 3 things that go to the hook are
1) membership status array holding id & name of the membership status - this is the result of the function & is the thing the hook is expected to alter
2) arguments array - basically all the stuff the function has calculated
3) membership array - whatever membership data is passed in - my expectation is that if people use the hook then over time they will hone this

NB - this is now in 4.5 & on the wiki

http://wiki.civicrm.org/confluence/pages/viewpage.action?pageId=120946716

[andrewhunt]

I meant going to CRM_Member_BAO_MembershipStatus::getMembershipStatusByDate(), but it's really not a big deal.  Great new feature!

[Eileen]

I think maybe you meant membershipTypeID? anyway - I think it's OK

[andrewhunt]

Yep--didn't notice I mistyped it until now.  Sorry for the confusion!

[Eileen]

Oh yeah - one reason for the redundancy - the membership array doesn't necessarily include the membership_type_id & I'd have to really work through those calling functions to be sure about what it has in it & whether it always does / always should - I am hoping that side of it will percolate a bit