API Migration from 1.x to 2.x

[xurizaemon]

There are a few threads springing up about migrating from 1.x to 2.x, so I'm kicking off  Wiki page (maybe a section) on migrating from 1.x to 2.x.

Migrating from 1.x API to 2.x API

This is part of issue CRM-2948

If there's a function you're missing in 2.x or you don't know how to achieve the same with the new API, please request docs in this thread, and if you have any useful notes or experience on migration, please feel free to write them up in the Wiki. Sample code, links to documentation or SimpleTest examples are all useful contributions.

[xurizaemon]

These are the functions we were using pre-2.0.

 * crm_contact_search() - becomes civicrm_contact_search()
 * crm_create_location() - becomes civicrm_location_add()
 * crm_create_note() - still available in 2.0, documented as deprecated, no replacement available yet?
 * crm_fetch_contact() - removed from 1.9 - see civicrm_contact_get()
 * crm_get_contact() - see civicrm_contact_get()
 * crm_get_contacts() - removed from 1.9 - see civicrm_contact_search()
 * crm_get_contact_memberships() - still in 2.0, documented as deprecated, no replacement yet?
 * crm_get_groups() - becomes civicrm_groups_get()
 * crm_get_locations() - becomes civicrm_location_get()
 * crm_get_note() - still available in 2.0, documented as deprecated, no replacement yet
 * crm_get_option_values() - see internal function CRM_Core_OptionGroup::valuesByID()
 * crm_get_relationship_types() - still available in 2.0
 * crm_get_tag() - still available in 2.0, documented as deprecated, no replacement yet?
 * crm_update_contact() - becomes civicrm_contact_add()
 * crm_update_location() - becomes civicrm_location_update()

These are the ones for which I can't see replacements documented in the Wiki at the moment, and which have been removed from 2.0.
 * crm_create_custom_field() - ?
 * crm_create_custom_group() - ?
 * crm_create_custom_value() - ?
 * crm_get_custom_field() - ?
 * crm_get_custom_group() - ?
 * crm_get_custom_value() - ?
 * crm_uf_edit_match() - this is a custom function we had added
 * crm_uf_get_match_id() - remains in 2.0
 * crm_uf_get_uf_id() - remains in 2.0

[xmatt]

I've heard that the custom option functions will not be available at all in 2.0, so you must use object methods directly. Can't say this is a design choice I agree with, but that seems to be how it is.

On the other hand, it looks like crm_uf_get_match_id() and crm_uf_get_uf_id() are still available in 2.0. Are they pegged for eventual removal? If so I probably will just never move to 2.0 since my code depends so heavily on those functions.

[xurizaemon]

It's not so hard to roll our own replacement API functions around those internal functions if we want the functionality to remain, but it makes sense to do this in co-operation with the core team ... and yes, I'd rather the functionality had stayed in core too Also - one of the functions I mentioned above had never existed in CiviCRM - it was an additional function I'd added to edit UF matches when syncing data from an external DB.

You're right, the crm_uf_* functions do appear to be still included in 2.0, and they are currently documented as remaining.

[Donald Lobo]

a fair number of the api calls were simple wrappers on static methods in our BAO objects. This was problematic for a couple of reasons:

1. We use the BAO objects directly and did not exercise the API. This led to the API not being maintained / upgraded, and as such was not tested very well. In general i'm more inclined to get folks to call the internal API's directly, and we should do a better job documenting / unit testing those components rather than maintaining two pieces of code.

2. Our email for feedback on how/what/why people are using the API did not get too many responses.

http://www.nabble.com/Feedback-Needed-on-Future-API-Development-to12892117s15986.html#a12892117

This led us to believe that not too many people were using the API

3. the crm_uf_* function are simple wrappers also

e.g.

Code:

function crm_uf_get_uf_id ( $contactID ) {
    require_once 'CRM/Core/BAO/UFMatch.php';
    return CRM_Core_BAO_UFMatch::getUFId( $contactID );
}

lobo

[dalin]

@xurizaemon note the wiki page I already started http://wiki.civicrm.org/confluence/display/CRMDOC/Changes+in+CiviCRM+2.  You might want to append your page to it and delete your original page. 
Also in regards to custom fields, note the last comment here http://wiki.civicrm.org/confluence/display/CRMDOC/Contact+APIs

[dflasse]

what about  crm_get_group_contacts()? I desperately need to be able to retrieve contacts from a group.

[Donald Lobo]

any specific reason you cannot use civicrm_contact_search( ) to retrieve all contacts from a group?

lobo

[xavier]

Hi,

Is there a more detailled doc on what the params can contain ?

For instance, what to put on it to retrieve a list of contact belonging to a group (or several) ?

http://wiki.civicrm.org/confluence/display/CRMDOC/Contact+APIs#ContactAPIs-civicrmcontactsearch%28%26%24params%29

(pointing to existing code would do, but as you said, the apis don't seem to be much used). Not sure it wouldn't be better to simply promote using directly the BAO classes, document them properly and get rid of the apis ?

X+

[dflasse]

Well, Xavier's right. What parameter should I use? I thought civicrm_contact_search( ) could only be used with values from the contact table

[dalin]

See here for examples on getting contacts from a group.

http://svn.civicrm.org/civicrm/branches/v2.0/test-new/SimpleTest/api-v2/GroupContactGet.php

Go one level up to see all sorts of API examples.

[dflasse]

Been there. Correct me if I'm wrong but function testGetGroupContacts( ) (see below) is meant to retrieve groups a contact belongs to and not contacts belonging to a group (I realize this is getting fuzzy). The parameter is contact_id and, in my case, I only have group_id.

   {
       $params = array( 'contact_id' => $this->_contactId );
       $groups = civicrm_group_contact_get( $params );
                 
       foreach( $groups as $v  ){
           $this->assertEqual( $v['title'], $this->_group[$v['group_id']]['title'] );
           $this->assertEqual( $v['visibility'], $this->_group[$v['group_id']]['visibility'] );
           $this->assertEqual( $v['in_method'], $this->_group[$v['group_id']]['in_method'] );
       }
   }

[Kurund Jalmi]

Using civicrm_contact_search() api to retrieve all contacts from a group.

       
        $groupId = 3;
        $params = array( 'group' => array( $groupId => 1),                                                                                                         
                                     'return.sort_name'    => 1                                                                                                       
                                   );                                                                                                                               
        $contacts = civicrm_contact_search( $params );                                                                                                     
         print_r($contacts);

HTH

kurund

[dflasse]

awesome! Thanks! I'll try as soon as I can get my hand on it. Wonderful.

[Dave Greenberg]

If you've figure out how to do something that wasn't clearly documented already, PLEASE continue to improve the relevant wiki API doc pages with tips, snippet examples, and/or links to an examples in the unit test files in the our svn repository - to make things a bit easier for folks going forward!