Contribute API

[Eileen]

Code: [Select]

I want to write a hook to make some information about a contacts contributions available as a token (ie. total donations from the contact, more recent donations).

I started writing the code below but was a bit surprised that if I pass in a contact_id and there is more than one parameter the result is an error. It does pass me out the details of the contributions in the error_data array and I could work with these but this doesn't seem like standard CiviCRM api behaviour and if it is *wrong* and it gets *fixed* later I could be in trouble at that point.

It would be relatively easy to change the api behaviour to be more standard (and I could submit a patch) - ie. I believe the standard is that the api calls should return an array of one or many contributions like the contact api does but of course this would impact other users. I guess this is normally managed through a 'version' or 'deprecated' option?

[code]
function civihook_civicrm_tokens( &$tokens ) {
    $tokens['civihook'] = array( 'civihook.contributionTotal', 'civihook.contributionTotal', 'civihook.contributionLastFive' );
}

function civihook_civicrm_tokenValues( &$values, &$contactIDs, $jobID ) {
require_once 'api/v2/Contact.php';
require_once 'api/v2/Contribute.php';
$params['contact_id'] = 1;
$contributions = civicrm_contribution_get($params);
echo "<pre>";
if ($contributions['is_error'] ==1 ){
   print_r($contributions );
}else{
 print_r($contributions['error_data'] );
}
die;
    // $value['civihook.contributionTotal'] = 'total amount from above functions' ;
    }

Returns

Code: [Select]

Array
(
    [is_error] => 1
    [error_message] => 2 contributions matching input params
    [error_data] => Array


<?php
[/code]

[Kurund Jalmi]

I think civicrm_contribution_get api should be used to get information on specific contribution record etc. Have you tried using civicrm_contribution_search

Kurund

[Eileen]

Ok - can do that - I was just assuming the standards Wes was advocating / trying to implement had been adopted

[Eileen]

Here is the spec Wes did - it's only covered briefly in it but he made the case at last year's dev camp that search should be ditched in favour of only using get - he had quite a movement going there for a bit

http://wiki.civicrm.org/confluence/display/CRM/API+Conventions

[Kurund Jalmi]

We have implemented few things and ii would be great if you can help us to implement this standards in the places where it is missing.

Kurund

[Eileen]

Well, the first thing is to be clear about what the standards are. Like I said, I understood that the search was to be deprecated in favour of get working in a way where it did both (effectively a search where passing in 'id' will return one object). Is that still a desired standard?

I'm happy to work with search or to submit a patch allowing 'version 3' behaviour (since that's used for location api) whereby the get works per Wes's spec if you pass in $params['version'] = '3'

[Donald Lobo]

hey eileen:

do u wanna chat with wes and xavier and see where things are and then start moving it forward

thanx

lobo

[xavier]

Can we plan an IRC chat sometimes next week ?

While we are around it, something that bothers me is that it returns an array with the keys being the ids. This works fine for a "search" function, but for a get for one, teg search on an external identifier, you end up with an array, that you have to foreach, even so you know there is only one.

Have a look at some code when it's done from crmAPI on smarty, workable, but clunky.

(I'm following with you by email)

X+

[Eileen]

OK - so if it's API here are the things that I have noticed for an 'agenda'

1) Get vs Search - what should the standard be?

2) security issue around ACLS not being respected

3) Location API - issues include it not accepting multiple addresses (hard-coded '1' array), not giving the option to update vs add phone numbers, not allowing search criteria e.g. 'is_primary'. I find this api pretty confusing which is a shame because it's so important

4) I notice the entity_tag_add doesn't return an ID - I presume this is because it hasn't been updated to the standards

5) I'd reallly like to add uf_id to what is returned from civicrm_contact_get but I was beaten by the code... If it was added it would make it easy to add to useful places like the de-dupe screen & the contact summary in addition to ad hoc uses

6) How does (should) 3.2 API handle soft-deletes vs hard-deletes - one issue I think I have seen is the risk of updating a deleted
contact when you intend to create a new one - but haven't spent much time testing this. Can you pass in a 'hard_delete' = 1 ?
 
7) Is there any way we could introduce a 'discover' function? The idea would be to return an array that represents what $params can be accepted. (Kind of making the API somewhat self-documenting)  I've muted this a couple of times and the reponse has been 'yeah - that would be really useful if it existed' - but the question of how easily it can be done and maintained is open

There are two possible approaches I can see:
1) use the fields function
2) get a list of fields from the relevant table
- in both cases you then need to manually add in extra possible parameters e.g. 'state_province_name'

There is a 'fields' function e.g.

    $fields = CRM_Pledge_DAO_Pledge::fields( );

But the problem I hit is that this function returns
'pledge_create_date' when the
    $pledge = CRM_Pledge_BAO_Pledge::create( $values );

function requires just 'create_date'

I'm not sure what rules exist around this.