Soft Credits

[idmacdonald]

In the near term, I need to implement some sort of contribution soft credits functionality for a client. The sort of thing I'm thinking of is the most basic usage case: There is a contribution of $20 that came from Jack, but I want to track that Jill is the fundraiser that raised the money. So, when I view Jack's contributions listing, I want to see a $20 'hard credit' and when I view the contributions page for Jill I want to see a $20 'soft credit'.

I am willing to work on development of this feature if appropriate, so that the soft credits feature can be integrated into CiviCRM core rather than just being a custom hack for this once client. Has anyone else worked on this soft of functionality?

If I wanted to work on developing this, could I have some pointers from those who know the CiviCRM API better than I about the best way of implementing it? I am a reasonable proficient PHP programmer, though I have more experience with the Drupal API than with that of CiviCRM (and they're very different!!).  I figure that I could invest 3 to 5 days of work in this. Does that sound at all feasible?

Thanks in advance for any feedback,
-Ian

[Donald Lobo]

hey ian:

can you try to expand a bit more on soft credits and the various features it can potentially have. Will help us understand it better. A couple of related questions:

1. when/how does the org decide that Jill gets a soft credit for that donation. i.e. where is this information extracted from?

2. can jill get a "partial" soft credit, i.e. $10

3. can jill and harry both get a soft credit for the same donation (full amount) or partial amount that equal to the full amount

4. how do soft credits interact with pledges / recurring donations

thanx for planning to incorporate into core. This should be possible and we can work with you to make it happen. Depending on your timing we can shoot to get this into the 2.2 release

lobo

[idmacdonald]

Hi Lobo,

Here are some answers to your questions:

> 1. when/how does the org decide that Jill gets a soft credit for that donation. i.e. where is this information extracted from?

The most common case I'm dealing with is something like Jill running a marathon and Jack being one of her sponsors. So, Jill might send in a list of all her sponsors and the amounts they pledged before the actual money comes in, or the check (or bank transfer or whatever) might just reference 'Jill Marathon'. But generally, when the contribution is entered (either manually or imported from CSV) there would just be two names attached to it.

> 2. can jill get a "partial" soft credit, i.e. $10

For my needs, no. But I can see that something like a 'partial soft credit' could be useful for other people.

> 3. can jill and harry both get a soft credit for the same donation (full amount)

No.

> or partial amount that equal to the full amount

I don't think this is really necessary for my client (their current system can't do that, AFAIK), but I could see how it might be a useful functionality for them.

> 4. how do soft credits interact with pledges / recurring donations

That's a good question! I'll have to consult with my client and get back to you on that one.

Thanks,
-Ian

[Dave Greenberg]

Thinking aloud here ... our next release includes a Personal Campaign Page (PCP) feature which is basically a specific sub-case of the Jill-runs-marathon / soft-credit scenario you've described. This implementation adds an optional foreign key to each contribution record which links the contribution to a personal campaign page that it "came from". Details are here:

http://wiki.civicrm.org/confluence/display/CRM/PCP+-+Phase+1+-+Specification

Should we look at generalizing this data model a bit so it can be used for other variations of "soft credits" - i.e. allows direct linkage to the "fundraising contact" record - rather than only "through the PCP"?

[petednz]

Sounds like the way to go - and would be worth raising this discussion with CAFOD if when they make their decision. Sounds like it begins to move closer to meeting their needs from memory.

[idmacdonald]

Hi folks,

I have consulted a bit more with my client and have also just gone though the Personal Campaign Page (PCP) spec that Dave linked to.

The PCP spec looks really good, though it generally looks much more complex than what I'm looking to do.

In our case, we are really just looking to have one additional field added to the 'contribution' form, to link the contribution to the fundraiser's contact record. So I would imagine some sort of auto-complete (Ajax) field to select 'Jill' and assign Jack's contribution as a 'soft credit' to her.

There is no need for 'partial' soft credits or for more than one person to get the 'soft credit' for the same contribution. And in my case, soft credits don't interact at all with recurring donations or pledges.

So, my requirement is to simply have one donation linked with the donor's contact record as well as a second contact (the sponsor). Then somewhere within the view of the sponsor's contact record we want to see a list of donations 'soft credited' to that person, either in the 'contributions' tab or on a separate one. And we would want to be able to produce reports based upon amounts 'soft credited' to contacts.

This client is not going to be using contribution pages at all. All donations are actually collected via other online systems or by manual means and will be entered into CiviCRM manually or via the import function (importing batches of donation data from CSV).

So that's what I'm trying to do! I suspect that this overlaps with the PCP feature in terms of the API for crediting contributions to a fundraiser, but a lot of the other functionality described there relates more to contribution pages and so is not directly relevant for me at the moment.

[Donald Lobo]

here's one potential way to do it (although some development will be needed)

1. We need to create a new Custom Field type called Contact Reference. This is basically an FK to a contact record (for folks familiar with CCK this is similar to node reference). If time permits, i'll try to squeeze this into 2.2. Potentially this contact refereence can be restricted by a civicrm group (to limit the contact. This can be implemented as an ajax combo box widget

2. Given the above, you can create a contribution group with two fields: amount (in case u want to deal with partial amount credit) and contact reference for the sponsor

3. For every contribution, folks can enter the sponsor if applicable

4. To see a list of soft credits in a sponsors view, implement the "tab hook"

5. Use custom search to produce a report

Step 1 is the gating factor here. If you have some development cycles and have php5 experience, you can help implement that part and ensure it makes it into 2.2

lobo

[idmacdonald]

Hi Lobo,

That sounds like a reasonable way to do it. I'd be willing to at least start work on a 'Contact Reference' field and see how far I get. Is there any reference anywhere to identify which codebase files relate to custom field types?

[Donald Lobo]

CRM/Custom/Form/Field.php
CRM/Custom/Page/Field.php
CRM/Core/BAO/CustomField.php

are probably the first few files you'll need to modify. You should do this on svn trunk. Ping us on IRC to help you get started etc.

http://embed.mibbit.com/?server=irc.freenode.net&channel=%23civicrm&forcePrompt=true

lobo

[idmacdonald]

Hi,

I've had a look at the code relating to custom field types and I have to say I wish there were a clearer API around the definition of field types. That's not to criticize the system, but to say that adding the new field type doesn't appear that straightforward to me. So, I can probably do some work on the Contact Reference field type, but I think that might be something I'll get to next month.

Since my client is quite keen to be able to import their existing data into CiviCRM in order to start using the system, and because most of their contributions will be imported from CSV in their day-to-day use anyway, I'm thinking that I might work on the infrastructure to store and display the sponsor information for each contribution and then come back to the UI for selecting sponsors. I can just use a custom integer field that stores the contact ID until the 'Contact Reference' field type is usable.

I know how to code custom searches for producing reports, so that should be fine. At this point I think I want to work on some code for displaying a list of soft credits in a sponsors view. Looking at the documentation on CiviCRM's hooks, it looks like I should create a Drupal module that uses 'hook_civicrm_links' to create a new tab to display the soft credits for a contact. Does that sound like a reasonable way to go about it? I assume that's what you mean by the 'tab hook'.

Thanks,
-Ian

[Michał Mach]

Ian,

We decided to implement soft credit functionality by extending newly introduced PCP functonality. It will be included in upcoming 2.2 release. You can find initial details of the implemention here: CRM-3874. Would you consider making it the base for the functionality you need to implement for your client? It should be available in repository snapshot version sometime in the middle of next week.

Let me know what you think.

Thx,
m

[idmacdonald]

Hi Michał,

I have had a look at the PCP functionality in the sandbox installation and it looks very good. I think it should be fine for tracking soft credits. However, one thing is missing:

I need to be able to set the 'Soft Credit To' field when importing contributions. I tested on the sandbox installation and I didn't see anything related to soft credits in the list of possible field mappings. I would think that a similar approach to importing the donor information would work: matching Contact ID, email address, or external identifier to the contact.

If the 'soft credit' field could be set when importing contributions, then I think that'd be everything I need. Let me know if there is any work that I can do to help get that into 2.2.

[Donald Lobo]

If the 'soft credit' field could be set when importing contributions, then I think that'd be everything I need. Let me know if there is any work that I can do to help get that into 2.2.

hey ian:

Would be great if you can build / extend the functionality to include soft credits in import. 2.2 is currently in code freeze and we are not planning to add any more features to it. Hopefully with your help this can make it into 2.3

lobo