CiviCRM Community Forums (archive)

Would make it easier indeed. Do we need to specify the event_id? it seems it's either too generic (ie. you have have several contact_id+event_id participants) or too specific (if the contrib id is given, the api could probably figure out direclty if a participant needs to be updated).

On a tangential note, didn't you work on some generic stuff for the IPN to automatically update the related entities when a contribution is confirmed/canceled?

So we want an API for contribution create that can support all of the post process functionality to complete the purchases on event registration pages and on contribution pages with memberships configured. In other words, we want to end up eventually moving the business logic out of the forms and into a big new function with an API interface. This would allow a REST call to do the same thing as one of those forms, and the db changes would all be done correctly, and emails sent out, etc. That's the goal.

Here's a modification of Eileen's call signature that provides all the needed info for both the financial side and for the non-financial/'business'/component side of creating participants, memberships, etc. As I don't have a good name for this, I just shoved the params for creating the object related to a line_item - a membership, participant, etc - into an array parameter line_item_params.  Although calls from existing forms would not mix participants with memberships, etc., I've put them all into one call for convenience here. I see the API looping through the

civicrm_api3('contribution', 'create', array(
  'total_amount' => 50,
  'financial_type_id' => 4,
  'payment_instrument_id' => 'Check',
  'contact_id' => 7,
  'line_items_with_params' => array (
    line_item_with_param => array(
      'line_item' => array(
        'entity_table' => 'civicrm_participant',
        'entity_id' => NULL,
        ....
      ),
      'params' => array(...), /* to create participant */
    ),
    line_item_with_param => array(
      'line_item' => array(
        'entity_table' => 'civicrm_participant',
        'entity_id' => NULL,
        ....
      ),
      'params' => array(...), /* to create participant */
    ),
    line_item_with_param => array(
      'line_item' => array(
        'entity_table' => 'civicrm_membership',
        'entity_id' => NULL,
        ....
      ),
      'params' => array(...), /* to create membership */
    ),
    line_item_with_param => array(
      'line_item' => array(
        'entity_table' => 'civicrm_contribution',
        'entity_id' => NULL,
        ....
      ),
      'params' => NULL, /* not needed */
    ),
    line_item_with_param => array(
      'line_item' => array(
        'entity_table' => 'civicrm_pledge_payment',
        'entity_id' => NULL,
        ....
      ),
      'params' => NULL, /* not needed */
    ),
  ),
);

The API function will use the name of the entity_table to determine what needs to be done with the params. I put the entity_id in for illustration purposes, but I don't think it should be in there in practice. Once the object if any is created, its ID will be used for the entity_id for the line_item. As appropriate, membership_payment, pledge_payment, etc records will also be created.

Currently, line_item.entity_table is set to 'civicrm_contribution' for memberships, which isn't quite the right semantics of this field as I recall them. To avoid backward incompatibility in case anyone is relying on this ;( we could complexify things by using a new and different arg to indicate that an object needed to be created for each line_item.

On an additional minor note about how the implementation didn't seem quite right to me, I also saw that on a pay_later payment for a single ticket that line_item.participant_count was 0, though I thought it would show 1.

Should we change the call from contribution.create v3 to something else? Don't we still need a hidden lower level _contribution.create to create just the contribution record?

I haven't delved down into the dependencies between the line_item_with_params. For example, I believe that 2nd and later participants set a parent_id to the first participant. I think some intelligence should remain in the form, e.g. if user wants different transaction for membership than for donation, the form would call API twice rather than once. But I don't have strong views on that.

Instead of introducing a new special param (always a pain to document/explain....) can't we create a ContributionLine entity an chain?
 

civicrm_api3('contribution', 'create', array(
  'total_amount' => 50,
  'financial_type_id' => 4,
  'payment_instrument_id' => 'Check',
  'contact_id' => 7,
  'api.ContributionLine.create' =>  array(
        'entity_table' => 'civicrm_participant',
        'entity_id' => NULL,
        ....,
        'api.participant.create'= array()
      ),
  'api.ContributionLine.create.2' => array(
      'line_item' => array(
        'entity_table' => 'civicrm_membership',
        'entity_id' => NULL,
        ....,
        'api.participant.create'= array()
      ),
...  ),
);

The API function will use the name of the entity_table to determine what needs to be done with the params. I put the entity_id in for illustration purposes, but I don't think it should be in there in practice.

No matter the syntax, I'm wondering if the chaining logic is in the right order: shouldn't it be Contrib->Participant->LineItem instead of Contrib->LineItem->Participant ?

I think that The LineItem could even be implicit: it you create a related entity within a main contribution.create, you can go ahead and create the needed LineItem.

Good point,

however, if we chain contribution.create->api.participant (or api.membership or...) then you can keep the implicit "hidden" line creation (you are right, the contribution line shouldn't be a "normal" entity chained in that case)

if you call contribution.create without any chaining, it works as today, if you want to have the correct lines, chain with api.participant, api.membership and the contribution.create is smart enough to know which line(s) to create

Would it work?

I'm going to take the example of webform_civicrm since that's what I'm most familiar with. It's also the only software I know of that attempts to create participants, memberships, and a contribution under a single transaction. As you can imagine doing so was a little hairy and I would welcome these proposed improvements.

I would particularly welcome getting rid of the membership_payment and participant_payment join tables, as those seem to be redundant with line-items (or at least they would be if membership line items reported the correct entity).

Re the proposal to add contribution_id to the line item table - this seems like a good change but could also result in some redundant data if not thought through completely.

I have some other questions about this but don't want to get too detailed too early. Maybe we should schedule a more in-depth discussion at some point.

A typical scenario of one participant having many line items is when a price set it used to present dinner options & accommodation options for a conference - causing the total price to vary on what is selected

I think there is some ambiguity about how line_items should be used. In webform_civicrm I use line_items only to represent a real entity (contribution, membership, or participant). But core civicrm seems to mostly use them to represent price set selections, e.g. choice of soup would be a line_item.
I tend to agree with Joe that "soup" is not an entity worthy of being recorded as a line item, but I'm not sure how we would get from point A to point B with that change.