CiviCRM Community Forums (archive)

I'd like to propose a complete overhaul of the way in which custom data is handled in api v3. (I'm not suggesting removing the current behaviour but to introduce a new approach & phase out the other stuff over time.).

Basically the API now has 2 new features:
1) chained api
2) the soon to be committed custom value API.

After talking with Coleman I'm thinking that instead of the current behaviour the new supported behaviour could be to chain the custom value api. So it would look like

civicrm_api('Contact','Get',array('version' => 3, 'display_name' => 'Fred Fish', 'api.customvalue.get' => array());

This would result in a contact get followed by a get on the customvalue api using the contact_id returned from the first get call (and any values in the array) as input for the second api call and would look something like the examples in

http://svn.civicrm.org/civicrm/branches/v3.4/api/v3/examples/ContactGet.php

This would require us to be really clear about the CustomValue api (and in particular how the values array is indexed). I've stuck in Coleman's description from IRC (which I haven't fully worked through yet)

(4:41:10 PM) eileen: yep - but what worries me is - it's remotely possible two fields could have the same index isn't it?
(4:41:17 PM) eileen: as they are in different tables
4:41:30 PM) colemanw: indexed on entity_id
(4:41:34 PM) colemanw: not field_id
(4:42:18 PM) eileen: hmm  std would be field_id but that's where it could conflict.
(4:42:40 PM) eileen: In the case of nested I stuck it to default to 'is_sequential' anyway as it seemed easier
(4:44:01 PM) colemanw: Currently here's how I've got it working:
(4:44:02 PM) colemanw: params: 'id' => '123, 'entity_type' => 'Activity', 'return.custom_2' => 1
(4:44:23 PM) colemanw: return: 123 => array('custom_2' => 'foo)
(4:44:36 PM) colemanw: but it gets better...
(4:45:03 PM) colemanw: params: 'id' => '123, 'entity_type' => 'Activity', 'return.custom_MyGroup_SomeField' => 1
(4:45:17 PM) colemanw: return: 123 => array('custom_MyGroup_SomeField' => 'foo)
(4:45:53 PM) colemanw: excuse me, it's colon separated, not underscore. So
(4:46:00 PM) colemanw: params: 'id' => '123, 'entity_type' => 'Activity', 'return.custom_MyGroup:SomeField' => 1
(4:46:07 PM) colemanw: return: 123 => array('custom_MyGroup:SomeField' => 'foo')
(4:46:20 PM) colemanw: if the field is multi-valued, you'll get ids as well
(4:46:40 PM) eileen: OK - I might just try to put it on  a forum post & get Erik & Xavier's input when they come on line because they way I'm thinking now is to change the main supported approach to custom fields & I'd like to canvas them
(4:46:41 PM) colemanw: return: 123 => array('custom_MyGroup:SomeField:33' => 'foo', 'custom_MyGroup:SomeField:35' => 'bar')

Hi,

What would be the benefit over custom_xxx ? Just a different syntax or to better handle multiple value or?

And should be camel cased, shoudn't it ? api.customValue.Get ?

X+

The benefit over custom_xxx I think is non-existent once you are familiar with it, the approach with using the actual field names is more consistent with the 'normal' API behaviour? And agree it should be camelcased...

I do get the clear name benefit, but (cf other thread), how to deal with arrays of arrays as param on an ajax call is quite not as simple as custom_42 or custom_SpecialCases1:WarmBeer

syntax question: do we need custom_ as prefix ?eg.
return.SpecialCases1:WarmBeer instead

return.custom_SpecialCases1:WarmBeer

In general, the chaining is super cool, but setting the param on that ajax is tricky

Might be easier to (finally) introduce the

civicrm/api/json

and do a civicrm/api/json?params={everythingjsonformatted}

case is a type - will support

type is also a typo

I am happy with the civicrm/api/json, agree that the ajax param could become very tricky. Most important IMO is that we take the simplest route available so that it is easy to explain and understand, therefore easiest to maintain and gives us most chance to attract lots of co-developers? My primary reaction would be that the json format does just that.

I can understand we need the return option so we do not break existing stuff, but could we also just use a api.CustomValue.Get and retrieve all available fields (depending on the parent?) or is the return required?


Is there a limit to the number of nested api calls?

OK, so we agree in principal with the approach & it becoming the standard.

We also agree we should implement a JSON URL to eventually replace the standard one

& I think we agree custom_ is not required on return properties

3 questions still from me:
1) it should take 'entity_id' rather than 'id' for the or whatever (this is consistent with how we would extend chaining for entity_tags
2) the values array from customValue should be indexed by groupid-fieldid rather than entity id - closer to the api standard
3) will json be happy with the : in the return syntax?

i checked last nite and php/smarty are not happy with the : separator. The only valid characters in a variable name are:

alphanumeric and underscore

this means we wont be able to use

$custom_groupName:fieldName

not sure if we can escape the : (did not find this in smarty yesterday)

Currently have no ideas other than an incredibly stupid one of using something like a triple underscore (___) and then fix the name munging code in civi (and the api) to always restrict it to two continuous __ in the db for custom groups/fields

It might not be too big a deal in PHP (since its mostly part of an array, so $values['custom_groupName:fieldName']) and also the same in json. However in Smarty that variable is exposed as $custom_gName:fName and hence we should figure it out

lobo