API v3 It does everything except make warm beer
What are we going to cover? <ul><ul><li>What problem does it solve? </li></ul></ul><ul><ul><li>Concepts and tools </li></u...
What problem does it solve? <ul><ul><li>Synchronising with an external system </li></ul></ul><ul><ul><li>Adding a custom w...
What is the API <ul><ul><li>A standardised way of accessing data in CiviCRM through code </li></ul></ul><ul><ul><li>More f...
What does an API call look like? <ul><ul><li>Entity </li></ul></ul><ul><ul><li>Action </li></ul></ul><ul><ul><li>Params </...
4 ways of accessing APIs PHP code REST {crmAPI} Ajax .crmAPI() PHP OO
A Pretty Intuitive example Functional requirement: Society visits companies in various countries, at the moment the visiti...
Cheat Sheet <ul><ul><li>Use the profile to get a list of companies to visit and the ability to change the company details ...
The profile <ul><ul><li>Profiles are a standard feature of CiviCRM </li></ul></ul><ul><ul><li>Can be used to access or upd...
The hook <ul><ul><li>I need to add additional data to the profile, and I use CiviCRM hooks to do that </li></ul></ul><ul><...
The API <ul><li>Finally the API is used to 'automatically' create an activity for the company and the visitor: </li></ul><...
Pop quiz for the free beer - is it possible to create a participant record with a linked contribution in a single API call
  &quot;yes, use API Chaining&quot; <ul><li>  </li></ul><ul><ul><li>API Chaining passes the results from 1 API call into a...
The problem <ul><ul><li>Garbage in/Garbage Out </li></ul></ul><ul><ul><li>Nothing in/ Nothing out </li></ul></ul><ul><ul><...
The solution ? <ul><ul><li>Introducing … </li></ul></ul><ul><ul><ul><li>Your personnal assistant </li></ul></ul></ul><ul><...
Miss MoneyPenny <ul><ul><li>From XMPP, with love </li></ul></ul>
Planned features <ul><li>Extensible API </li></ul><ul><ul><li>new entities </li></ul></ul><ul><ul><li>new actions </li></u...
Testing    The API is heavily tested but there are still a lot of features not covered. If you want it to work after your ...
Recent features   <ul><ul><li>Chaining </li></ul></ul><ul><ul><li>Extra functions </li></ul></ul><ul><ul><ul><li>getsingle...
Recent features (in the generic API) <ul><li>These functions work on some API and are being implemented across them (as te...
Upcoming SlideShare
Loading in …5
×

CiviCRM API v3

2,234 views

Published on

It does everything except make warm beer

by Xavier Dutoit, Erik Hommel and Eileen McNaughton

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,234
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
8
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

CiviCRM API v3

  1. 1. API v3 It does everything except make warm beer
  2. 2. What are we going to cover? <ul><ul><li>What problem does it solve? </li></ul></ul><ul><ul><li>Concepts and tools </li></ul></ul><ul><ul><li>A Pretty Intuitive example </li></ul></ul><ul><ul><li>A feel for the cutting edge </li></ul></ul><ul><ul><li>Advanced example </li></ul></ul><ul><ul><li>The future is looking at you </li></ul></ul><ul><ul><li>Q/A ? </li></ul></ul>
  3. 3. What problem does it solve? <ul><ul><li>Synchronising with an external system </li></ul></ul><ul><ul><li>Adding a custom workflow </li></ul></ul><ul><ul><li>Developing a new interface </li></ul></ul><ul><ul><li>Changing the default behaviour </li></ul></ul><ul><li>  </li></ul><ul><li>Any time you need to Create Read Update or Delete... </li></ul><ul><li>almost anything (contact, event, contribution...) </li></ul><ul><li>  </li></ul><ul><li>Learn it once, use it everywhere </li></ul>
  4. 4. What is the API <ul><ul><li>A standardised way of accessing data in CiviCRM through code </li></ul></ul><ul><ul><li>More future proof than SQL or using internal functions </li></ul></ul><ul><ul><li>The most supported way to interact with CiviCRM data from custom code </li></ul></ul><ul><ul><li>Better tested (1200 tests and counting...) </li></ul></ul>
  5. 5. What does an API call look like? <ul><ul><li>Entity </li></ul></ul><ul><ul><li>Action </li></ul></ul><ul><ul><li>Params </li></ul></ul><ul><ul><li>Contact (or one of 45 others!) </li></ul></ul><ul><ul><li>Get, Create, Delete, Replace, getcount, getsingle, getvalue, </li></ul></ul><ul><ul><li>Array of relevant variables </li></ul></ul>API Explorer: /civicrm/ajax/doc List of params: /civicrm/api/doc (as of the next version)
  6. 6. 4 ways of accessing APIs PHP code REST {crmAPI} Ajax .crmAPI() PHP OO
  7. 7. A Pretty Intuitive example Functional requirement: Society visits companies in various countries, at the moment the visiting agents send in a report of the visit by email. This should be done online Solution in CiviCRM:   ?
  8. 8. Cheat Sheet <ul><ul><li>Use the profile to get a list of companies to visit and the ability to change the company details </li></ul></ul><ul><ul><li>Adda custom data set with activities of a specific type to hold the additional data </li></ul></ul><ul><ul><li>Use a hook to enhance the profile with additional data </li></ul></ul><ul><ul><li>Use the API to add companies to a group and create an activity </li></ul></ul>
  9. 9. The profile <ul><ul><li>Profiles are a standard feature of CiviCRM </li></ul></ul><ul><ul><li>Can be used to access or update CiviCRM data from 'outside' </li></ul></ul><ul><ul><li>  In this case, the standard contact profile gives me a list of companies and a possibility to update the company details (address etc.) </li></ul></ul><ul><ul><li>  But I need more...... </li></ul></ul>
  10. 10. The hook <ul><ul><li>I need to add additional data to the profile, and I use CiviCRM hooks to do that </li></ul></ul><ul><ul><li>Hooks can be used to insert your own code and processing in the CiviCRM processing </li></ul></ul><ul><ul><li>In this case I used the buildForm hook to add data to the profile, and use the API to retrieve some additional contact data that is not on the profile:  </li></ul></ul><ul><li>$contactParms = array( </li></ul><ul><li>    'version' => 3, </li></ul><ul><li>    'check_permissions' => false, </li></ul><ul><li>    'contact_id' => $userID); </li></ul><ul><li>$result = civicrm_api( &quot;Contact&quot;,&quot;get&quot;, $contactParms ); </li></ul>
  11. 11. The API <ul><li>Finally the API is used to 'automatically' create an activity for the company and the visitor: </li></ul><ul><li>$activityParms = array( </li></ul><ul><li>  'version'              => 3, </li></ul><ul><li>  'check_permissions'    => false, </li></ul><ul><li>  'source_contact_id' => $sourceID, </li></ul><ul><li>  'target_contact_id' => $id, </li></ul><ul><li>  'activity_type_id' => 32, </li></ul><ul><li>  'subject'          => &quot;Bezoekverslag website&quot;, </li></ul><ul><li>  'details'          => &quot;blahblah&quot;, </li></ul><ul><li>  'status_id'            => 2, </li></ul><ul><li>  'activity_date_time'  => $activityDate, </li></ul><ul><li>  'custom_35' => $veranderingJn); </li></ul><ul><li>$result = civicrm_api( 'Activity', 'Create', $activityParms ); </li></ul>
  12. 12. Pop quiz for the free beer - is it possible to create a participant record with a linked contribution in a single API call
  13. 13.   &quot;yes, use API Chaining&quot; <ul><li>  </li></ul><ul><ul><li>API Chaining passes the results from 1 API call into another. </li></ul></ul><ul><li>  </li></ul><ul><ul><li>API chaining relies on the fact that useless values are dropped by the receiving function </li></ul></ul><ul><ul><li>If the chained function is the same as the higher level function 'id' is passed through from the higher function </li></ul></ul><ul><ul><li>otherwise the id is passed through as '$entity_id' AND as 'entity_id', 'civicrm_entity' is also set. </li></ul></ul><ul><ul><li>'version' & 'sequential' are always set  </li></ul></ul><ul><li>  </li></ul><ul><li>http://svn.civicrm.org/civicrm/branches/v3.4/api/v3/examples/Participant/CreateParticipantPayment.php </li></ul>
  14. 14. The problem <ul><ul><li>Garbage in/Garbage Out </li></ul></ul><ul><ul><li>Nothing in/ Nothing out </li></ul></ul><ul><ul><li>My users are too lazy to open a browser </li></ul></ul><ul><ul><ul><li>I'm even lazier than they are </li></ul></ul></ul>
  15. 15. The solution ? <ul><ul><li>Introducing … </li></ul></ul><ul><ul><ul><li>Your personnal assistant </li></ul></ul></ul><ul><ul><ul><li>Always awake </li></ul></ul></ul><ul><ul><ul><li>That knows everything </li></ul></ul></ul><ul><ul><ul><li>Always ready to take a note </li></ul></ul></ul>
  16. 16. Miss MoneyPenny <ul><ul><li>From XMPP, with love </li></ul></ul>
  17. 17. Planned features <ul><li>Extensible API </li></ul><ul><ul><li>new entities </li></ul></ul><ul><ul><li>new actions </li></ul></ul><ul><li>  </li></ul><ul><li>More complete </li></ul><ul><ul><li>same filters/options everywhere </li></ul></ul><ul><ul><li>more sort criteria </li></ul></ul><ul><ul><li>improve underlying BAOs </li></ul></ul><ul><li>  </li></ul><ul><li>We need you! </li></ul><ul><li>More tests </li></ul><ul><ul><li>a test is a contract, if you use the api in a different way, write a test and contribute </li></ul></ul>
  18. 18. Testing   The API is heavily tested but there are still a lot of features not covered. If you want it to work after your next upgrade ... help make sure it's tested
  19. 19. Recent features   <ul><ul><li>Chaining </li></ul></ul><ul><ul><li>Extra functions </li></ul></ul><ul><ul><ul><li>getsingle </li></ul></ul></ul><ul><ul><ul><li>getvalue (needs return=array('valuename') </li></ul></ul></ul><ul><ul><ul><li>getcount </li></ul></ul></ul><ul><ul><ul><li>replace </li></ul></ul></ul><ul><ul><li>format.only_id </li></ul></ul><ul><ul><li>format.is_success </li></ul></ul><ul><ul><li>sequential </li></ul></ul>These are implemented in the 'wrapper' function & work across all API  
  20. 20. Recent features (in the generic API) <ul><li>These functions work on some API and are being implemented across them (as tests are written ) .  </li></ul><ul><li>  </li></ul><ul><li>options('limit'); </li></ul><ul><li>options('sort'); </li></ul><ul><li>options('sort');  </li></ul><ul><li>strtotime date handling (e.g. 6 months ago); </li></ul><ul><li>filters e.g. </li></ul><ul><li>  'filters' => array(       'activity_date_time_high' => '20120101000000' ,     ), </li></ul><ul><li>  </li></ul>

×