Contribution action functions

[Eileen]

I'm looking at the fact that there are some contribution updates that have actions associated with them & wondering how that fits in our api model.

For example - there is a difference between updating a contribution to having a status of refunded or completed and refunding or completing the transaction. We currently have a specific action for completetransaction which, in addition to updating the status, also ensures related entities are updated and sends out confirmation emails. This leverages the actions taken when updating from IPN.

I'm fairly sure, however, that updating a transaction to cancelled or refunded does not trigger the business actions in the baseIPN class for that sort of transaction. We also would want having the ability to pass a refund request to the payment processor at some point.

So, at the very semantic level - we have said the action should always be 'create' with status_id  = 3 (e.g) but then we would be staring in the face of more magic params ('action_status_update_with_processor', 'send_emails', 'update_related_entities') since I'm not sure we can start adding that as std business logic.

Which leaves the other path of having things like 'recurring_contribution.cancel' as it's own action. Obviously the question is - where would it stop. At this stage it seems possible that we would have actions for change-of-status within reserved statuses.

Thoughts ? Is our current 'everything is a create' too brittle for more nuanced business logic?

[nicolas]

Eileen,

This is a very interesting point, and there is no easy answer as it depends on the use case for which the API is used.

If you are using the API to implement a contribution form, you would want all business logic to be executed on creation and status change for the contribution.
If however you are using the API to implement a synchronization with an outside giving system, you would not want this business logic to be executed as logically confirmation emails, payment processor updates, etc would have been executed by the other giving system.

So ... could the CompleteTransaction action be extended to accept different statuses and perform specified business logic, ie.
      civicrm_api3( 'Contribution', 'CompleteTransaction', array(
          'id' => 728,
          'status' => 'Canceled',
      ));
would cancel the contribution and perform all business logic actions? (maybe rename 'CompleteTransaction'  to 'Execute' or similar)

Could this principle be needed for other entities as well? What about Pledge? Participant? Mailing?

--Nicolas.

[JonGold]

Is it perhaps worth adding a new param to the API to indicate whether business logic actions should be run or not?  I realize that currently the actions taken may not be consistent, which means that this might be an API v4-focused suggestion.  It seems inevitable that support for both triggering and bypassing business logic will be needed for a variety of API activities. 

I can even think of some oddball cases right now - for instance, updating civicrm_address.master_id (for shared addresses) with an address that belongs to an organization triggers a function to set the Current Employer relationship.  Bypassing business logic would allow you to update the master_id without creating a relationship.