CiviCRM Community Forums (archive)

Hello, I'm new to working with the civicrm API and had a few questions, I am afraid I'm missing something small and am going to end up reinventing the wheel

I want to use civicrm_uf_id_get with the REST interface, the function exists in the api/v2/UFGroup.php file.
When I do rest.php?q=civicrm/uf_group/id_get.....  the REST.php concats the path and checks to see if the function civicrm_uf_group_id_get exists in UFGroup.php and gives an error since it doesn't (I want it to look for civicrm_uf_id_get)

So I read the documents on your API conventions and this function also happens to be one of the functions which doesn't conform to the $params behavior (its expecting a contactId).  Whats the best way for me to use this function over REST in my own project without causing future conflicts as you make changes to the API?  

My first blush idea / attempt is to wrapper the built in api function while still conforming to the REST function naming / params convention - so I'm doing something like this in api/v2/UFMisc.php

<?php
   
    include_once('UFGroup.php');

    function civicrm_uf_misc_id_get($params) {
        
        if(!is_array($params)) 
          $params = array('contact_id' => $params);
      
        $contactID = isset($params['contact_id'])?$params['contact_id']:NULL;
    
        if(is_null($contactID)) {
          return civicrm_create_error('Function takes param of array("contact_id" => N)');
        }
    
        return civicrm_uf_id_get($contactID);
    }
    

Is there any easier way then this?  as far as I can tell I can only use civicrm_uf_group_create and the civicrm_uf_join_* functions via REST

http://wiki.civicrm.org/confluence/display/CRMDOC33/Profile+APIs




I was also wondering if there any method of doing campaign contribution page creation, or pcp creation via the API as well as soft contributions.   If not, whats the best methodology for writing the api so I can contribute it back to the core project?  

[Edited to fix wording, on my previous civi project we referred to each fundraising page as a campaign (instead of a contribution page), pcp's being personal campaign page confused it more]

My preferred option is to add the uf_id into the contact_get as a return option (ie. you could put in $params['return.uf_id'] in your parameters. Xavier is a bit more of a BAO purist & might disagree but it's an option I've often wanted in the contact_get.



Re soft contributions - you can certainly create soft contributions by using the contribution add API in v2

$params['soft_credit_to']

You may also be able to add them as a return value

$params['soft_credit_to']

My preferred option is to add the uf_id into the contact_get as a return option (ie. you could put in $params['return.uf_id'] in your parameters. Xavier is a bit more of a BAO purist & might disagree but it's an option I've often wanted in the contact_get.

Having that as a feature would be a handy helper so things didn't have to be done in two steps.   Since for my particular project I think I'll also need to use civicrm_uf_match_id_get is there another function that I can get that from?

Agree with you, that's a mistake in the code, not conform with the naming convention. Could you fix and submit a patch ?

(the UF is a bit of a grey area for me, I always mix up the UF as stuff that links civi contact and CMS user and the custom sets).

Anyway, the variable has to be param (an array) indeed, and the name of the function civicrm_entity_action within v2/Entity.php

...

There is a function helper to deal with verifying the param: civicrm_verify_mandatory (in api/v2/utils.php). Check the code for instance in Tag.php for an example of usage.

Thanks for the tip on the civicrm_verify_mandatory, the reason why I put the check for is_array (and shoved a non array into an fake params array) is that the current definition for the functions paramaters listed a contact_id, so I when I first was writing it I was writing it in place in UFGroup (to replace the existing civcrm_uf_id_get) and wanted to preserve legacy behavior incase some other part of the code used that function.  


So as for resolving the naming / params whats the most recommended method for doing this:

Should I create a UF.php, put civicrm_uf_id_get and civicrm_uf_match_id and move the (corrected param versions) of these functions out of UFGroup.php (I don't see them being used by anything in UFGroup.php)?  

Or

Should I fix them in UFGroup.php, and just make UF.php do an include('UFGroup.php') to satisfy the REST interfaces function lookup - if doing this I could also add a UFProfile.php and UFField.php to move towards making those usable.

Or

I dont think we have campaign/pcp/soft contrib api's as yet. If you can conform to the standards (as they exist and u interpret them) and submit them as patches that would be a great first start. Also please include unit tests. Most of the API team (erik, eileen, xavier, coleman) should be back next week, so pinging and chatting with them on irc should help

And the standards are these - http://wiki.civicrm.org/confluence/display/CRM/API+Conventions ?

I read somewhere (probably the forums) about a new version of the API's coming, are they going to be essentially the same just with changes to the functions which don't use a $params or are they a large departure from the api/v2 structure?   I'm still evaluating for this project if we are going to do everything through the API (so we can use it in more situations / configurations ) or if I'll be reusing some previous code that just used the internal functions directly for creating campaigns and pcps, so I'd like to know if I'm going to have to rework a lot of this down the road a little bit.

I upgraded my install to 3.3.1 so that I could make sure I was current and have found what I think is a bug

in civicrm/CRM/Utils/REST.php line 168-170   In some situations the array thats being foreach'd contains hash => string entries instead of hash => array entries


foreach ( $result as $n => $v ) {
               
$xml .= "<Result>\n" . CRM_Utils_Array::xml( $v ) . "</Result>\n";
           
}

$result =

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

....

so the loops being called like:   

CRM_Utils_Array::xml( 1 );   
CRM_Utils_Array::xml( '4 contributions matching input params' );
CRM_Utils_Array::xml( Array( [2] => Array ( ..... );


Heres a sample of the output:


(this is a query ran without returnFirst set, so I'm expecting it to deliver the list in Result->error_data)


<?xml version="1.0"?>

<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Result>
</Result>
<Result>
</Result>
<Result>
    <2>
        <contact_id>2</contact_id>
        <contact_type>Individual</contact_type>
...

Heres what I expect to get ( basically how the else functions - $xml .= "<Result>\n" . CRM_Utils_Array::xml( $result ) . "</Result>\n"; )

<?xml version="1.0"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Result>
    <is_error>1</is_error>
    <error_message>4 contributions matching input params</error_message>
    <error_data>
        <2>
            <contact_id>2</contact_id>
            <contact_type>Individual</contact_type>

I'm getting this behavior when trying to do:
    /sites/all/modules/civicrm/extern/rest.php?q=civicrm/contribution/get&contact_id=2&key=YOUR_KEY&api_key=USER_API_KEY

Yeah, I'll submit a patch.  Whats a good test case for one that should return this first case so that I can be sure not to break anything?

Ryan,

In answer to your question about v3 of the API - v3 is primary about moving towards the standards that have been our goal for some time without having to handle backwards compatibility. The instance you have hit is a good example - to patch it within the v2 api folder it would need to handle both an array (correct) and the existing variable (incorrect) which make it tedious & ugly so we will ship v3 in a new folder (can you guess what it's called?).

There is an SVN trunk set up for v3 - not quite sure our timeframes yet ... and we are actively recruiting to the API team.

Re the file name - I think the reason Xavier & I are confused about that file is it is poorly named (actually I find the use of the term 'userframework' in Civi to refer to anything other than the UF Match table confusing!). So, I vote you move the function into v3/UF.php

Okay, good to know its essentially the same just not guaranteed backwards compatible, that should help me justify the time investment towards writing it.   I'll maintain my diffs and then submit a patch when completed.  I appreciate all the help and feedback, I'll ask less questions once I'm comfortable in understanding how to determine whats a certain way on purpose, and what just hasn't been reworked yet


Do you have any comment on the xml thing I mentioned a couple posts up?  Since the xml function is recursive it seems to handle hierarchical just fine so I'm not sure if I'm just looking at left over code or if I'm missing some bigger purpose.

BTW questions are fine - ask away!