CiviCRM Community Forums (archive)

So, having implemented the new formats & chaining we have talked about, I can some limitations on how the unique format of CustomValue works in the api v3 framework. It may turn out to be impossibly but here's the thoughts I have.

The formats (getSingleValue, only_id, getCount, getSingleEntity) don't work (on default settings) in a useful way on custom_value because it has an extra layer.

Of the new api formats the one I would probably use would be

civicrm_api('contact','get',array('display_name' => 'Batman',
                                           'version'=> 3,
                                          'api.CustomValue.getSingleValue' => array('return' => 'custom_123')));

then that would functionally replace

civicrm_api('contact','get',array('display_name' => 'Batman',
                                            'version'=> 3,
                                            'return' => 'custom_123'));

As in both cases the value is equally easy to access

$result['values'][$result['id']['custom_123']
$result['values'][$result['id']['api.CustomValue']

- No foreachs & as long as I know the field value  I know exactly how to access it

(note that with regards to the contact API it may not ever make sense to phase out the current custom handling as it is done via SQL & is probably more efficient - in all these examples Contact is probably the wrong entity to use but it's easy to come up with examples)


The other thing I can see as a limitation looking at the new formats is that we will want to be able to use CustomValueGet to search by value rather than just by entity at some later point & to use that as part of a chain

At that point the call to 'get all contacts who love Batman' & change their prefix to 'hero'

civicrm_api('CustomValue','get',array('123' => 'Batman',
                                           'version'=> 3,
                                          'api.Contact.create' => array('prefix' => 'hero'));

(entity_id should be passed in automagically as 'id' -  hopefully this currently happens with 'note').


For this to work we'd need 'entity_id' & 'entity_table' in the results array.

I think it would need to look something like the below

(I'm not advocating necessarily reverting to keeping the 'custom_123'  - mostly the example is just thinking about keys & the depth of the arrays/ types of fields that are in it. This is just trying to work through what would fit with the 'full capacity of chaining'. Also, not quite sure how you'd chain on getting extra detail from CustomField api if you wanted it)

          'api.CustomValue.get' => array(
              'is_error' => 0,
              'version' => 3,
              'count' => 3,
              'values' => array(
                  '1-2' => array( //where custom group is 1 & field value is 2
                          'entity_id' => '123',
                          'entity_table' => 'civicrm_contact',
                          'custom_222' => 'value 4',                       
                    ),
                  '4-3' => array(
                          'entity_id' => '123',
                          'entity_table' => 'civicrm_contact',                     
                          'custom_254' => 'value 2',
                          'custom_244' => 'warm beer',
                          'custom_288' => '',
                        ),
                   '4-4' => array(
                          'entity_id' => '123',
                          'entity_table' => 'civicrm_contact',
                          'custom_254' => 'value 3',
                          'custom_244' => '',
                          'custom_288' => '',
                        ),
                    ),

I suspect the 'sequential' param still wouldn't work without some bullying with the indexing above.

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

That was a good question. I don't think it was fully answered, and that probably led to some miscommunication. I think there are at least three issues that have been batted about:

Issue 1. As part of the api/v3 project, Eileen and Xavier have done a lot of work to improve the consistency of different API operations.  One source of inconsistency in api/v2 was custom data -- i.e.  the 'Contact' API supported lots of custom data magic, but the APIs for other entities were spotty or non-existent.  To achieve greater consistency, we need a generic way to process custom-data for all entities.

Issue 2. The "custom_123" convention makes it hard for API adopters to reuse their PHP/Smarty/JS code (or, for that matter, to reuse email templates, profile forms, or smart groups) on different sites.  This leads third-party developers to improvise ways
to identify custom fields (e.g. using a PHP "define" and then tweaking it on each installation; using a library+admin page to let users tweak the mapping; or matching a regular-expression to a SQL column name or field label). To improve portability, we need better programmatic symbols for custom fields.

Issue 3. Single-row CustomGroups have different requirements than multi-row CustomGroups.  For single-row CustomGroups, the use of an extra SQL table is "a mere implementation detail" -- one can intuitively think of each CustomField as extending the original entity.  For multi-row CustomGroups, the lifecycle looks more like "civicrm_participant", "civicrm_contribution", or "civicrm_email" -- i.e.  you need to the ability to independently CRUD several rows. However, the old approach managed to tackle both single- and multi-row data with some notational magic -- but notational magic is functionally incomplete, harder to grok, harder to integrate. ("OK, so I can add a new row with -1; how do I delete one?") To improve data management, we need clear (and different) conventions for processing single-row and multi-row data.

The fact that there are three issues makes it harder to find solutions. For example, xavier made this useful observation:

Been confirmed that the field name (well label but as one generates the other...) is already checked to be unique.  Ie.  we can drop the "my_group:some_field" and go directly "some_field (well probably "custom_some_field")

This is good news for issue #2 -- it's much more natural (and more portable) to write code for "some_field" rather
than "custom_123" or "somegroupthatmightchangeonothersites:some_field". It's tangential to issue #1
(because it doesn't provide any generic helpers) and it's counter-productive for issue #3 (because consumers working with multi-row CustomGroups need to see the group structure).

Anyway, I'm not certain about how each proposed solution addresses each problem, but maybe it will help to have an explicit problem statement.

Hi,

Revising on IRC my position: we shouldn't hide the set/group at all, quite the opposite

we need to add an id in the array that is returned. Trying to think if we expose the group:

Create a new record mono or multi-value

api.customField.create
array(
    'set' => 'set_A',
    'entity_id' => 123,
    'my_single_field' => 'updating the value'),
    'my_multi_field' => 'inserting a value')
   );


Update a record

api.customField.create
array(
    'set' => 'set_A',
    'id' => 42,
    'my_single_field' => 'updating the value'),
    'my_multi_field' => 'inserting a value')
   );

If you want to create/update several records from the same multi value set or several mono value, api.chain is your friend.

What do you think ?

A couple of notes from IRC - Xavier's example would be id indexed by the id in the custom table. His example relies on only getting one group @ a time - hence, no conflicts.

To my mind as long as we add entity_id & entity_table to Coleman's example the 3 proposed would work within the API structure.

I do note that using X's example the 'id' & 'count' fields in the return array become meaningful.

Hi,

(kind of hard to read a log

So the BAO is hiding the set? I'm not sure that helps a lot (ie. you know where you put your custom fields) and is potentially a way of making a wrong structure of custom sets (too much/too many/wrongly grouped) without realising it.

Anyway, for mono values, would work to have a api.customFields.get ( with set = array (set1,set2) or optional).

Not convinced about how clever it is, but could work as well to have set optional on the create

For update, I think having an id on the create and several set is black magic at best and a way of letting users hang themselves.

For multi-values, anything more clever than my suggestion is too clever for its own good I think.

Colemans, not sure I understood your point about the complexity of the code.

X+