Creating Custom Values using API

[bpmccain]

I'm trying to import a new Individual contact using the API. I can create the contact and the address no problem, but I am having trouble filling in the values for the custom fields that I have setup for Individual contacts.

I'm pretty sure my problem is around the keys. If I look in my database under civicrm_value_custom_group_name, I can see each row for custom values I have entered using the GUI. In the below code, the 'id' number I am using is the entity_id number from this table.

The other keys are the column headings from this table, but these are slightly different from the names in civicrm_custom_field table.

Any ideas? Thanks in advance

Code: [Select]

$additionalParams = array('version' => 3,
'id' => $contactID,
'official_provincial_riding_1' => $ridingNumber,
'official_provincial_riding_poll__6' => $pollNumber,
'official_provincial_riding_poll__10' => $pollSuffix,
'address_id_11' => $addressID);

$results=civicrm_api("CustomValue","create", $additionalParams);
Brian

[Eileen]

Hi,

The customValue api is a new way we are looking at to do custom fields. Unfortunately a version made it into the release that I don't think is final (last seen I was hoping that Coleman and Xavier would agree the last few points).

However, for 90% of use cases the CustomValue api is not required as you can simply do this

$params = array('version' => 3,
                       'display_name' => 'Clarke Kent',
                      'custom_12' => 'red cape')
civicrm_api('contact','create',$params);

that will create a contact called 'Clarke Kent' with custom field # 12 set to red cape.

If you want to update an existing contact pass in the 'id' field

Eileen

[bpmccain]

Thanks. I will give that a try.

[bpmccain]

Thanks Eileen, that worked great for me.

I also wasn't aware that you had to use custom_1 etc as the key instead of the actual name of the key (in my case official_provincial_riding_1).

Maybe this could be added to the documentation somewhere for the api. Happy to contribute to it, but not sure how.

Brian

[JoeMurray]

Thanks for thinking of helping out with the documentation. It's always and important thing for open source projects like CiviCRM to constantly improve and polish.

There are various versions of the documentation. The inline documentation in the code can be editted then a patch file created capturing your changes with diff.

The best way is to set yourself up with subversion (http://wiki.civicrm.org/confluence/display/CRMDOC40/Installing+CiviCRM+from+subversion+%28SVN%29+repository) then after editting a code file, use a subversion tool or command to create the patch, eg:

$ cd [mydocroot]/sites/all/modules/civicrm
$ svn diff api/v3/Contact.php > mypatch.txt

To edit the wiki documentation, you need to register on the wiki, then login, then go to the page, eg http://wiki.civicrm.org/confluence/display/CRMDOC40/CiviCRM+Public+APIs and click the edit button.

[JoeMurray]

To edit the FLOSS Manual, go to http://booki.flossmanuals.net/, create an account, then sign in, click on the CiviCRM book's link, and edit the relevant section of the book. Not sure if there is an approval process on the privileges for editting the book. If so, try contact michaelmcandrew

[Eileen]

I think it would make sense to include a module like the once Brian has just written in Core called something like api_example_module which just registers a URL & does 1 api get call when you go to that URL if you turn it on.

[Kirk]

Hi bpmccain,

Your attempt to use the CustomValue API failed because the parameters were not correct.

There are different ways you can specify custom fields - with IDs, names or labels. However, it looks like you tried using column names (civicrm_custom_field.column_name) which is not valid.

You could have used database IDs (civicrm_custom_field.id) thus:

    $additionalParams = array(
        'version' => 3,
        'id' => $contactID,
        'custom_1' => $ridingNumber,
        'custom_6' => $pollNumber,
        'custom_10' => $pollSuffix,
        'custom_11' => $addressID
    );

Alternatively you could have identified the field using its name (civicrm_custom_field.name) or label (civicrm_custom_field.label). With either of these you must also supply an argument to identify the group to which the field belongs using the group's name (civicrm_custom_group.name) or title (civicrm_custom_group.title). The arguments are separated by colons, so your code would look something like this:

    $additionalParams = array(
        'version' => 3,
        'id' => $contactID,
        'custom_riding_number:official_provincial_riding' => $ridingNumber,
        'custom_poll_number:official_provincial_riding_poll' => $pollNumber,
        'custom_poll_suffix:official_provincial_riding_poll' => $pollSuffix,
        'custom_address_id:address' => $addressID
    );

This assumes that the groups are not multi-valued. If they are then you need to add an extra numerical argument; the ID of the custom value record, or -1 for a new value, e.g.:

        'custom_poll_number:official_provincial_riding_poll:-1' => $pollNumber,

Group name/title can be left blank if the field name is globally unique, e.g.:

        'custom_poll_number::-1' => $pollNumber,

Some of this I got from the comments at the top of civicrm/api/v3/CustomValue.php. Unfortunately these comments are incomplete and misleading. They state that arguments should be supplied in the order of group_name:field_name but I had to look into the code of that file and of civicrm/CRM/Core/BAO/CustomField.php to determine that the expected order is actually field_name:group_name.

I must say I find it disappointing that CiviCRM 4 was released with the custom fields API so unfinished and undocumented. This problem has cost me a lot of time and I'm sure I'm not the only one who's been struggling with it.

[Donald Lobo]

Hey kirk:

parts of api v3 are still a work in progress, but it has significantly improved the state of the API and its future.

The custom value API is still being discussed and there is an open issue:

http://issues.civicrm.org/jira/browse/CRM-8131

Would be great if you can help with that issue so others can be saved hours. That will help the project and the community

thanx

lobo

[Eileen]

It's unfortunate CustomValue was included in a release because the version that was included was not the final one

[ymmatt]

So the above solution works well for fields that don't allow multiple entries, but what if they allow multiple entries, how do you add a new set of entries using the api? can you?

Edit:
Decided to take my own advice and "try it and see" and lo and behold it does what I want and adds a new record, very cool

[artfulrobot.com]

I get an exception when trying to set a custom field's value on an existing contact that has not had the custom field value set. It is not a multiple value field.

e.g. this API call (derived from API explorer)
example.org/civicrm/ajax/rest?version=3&custom_7=yay&id=105&fnName=civicrm%2FContact%2Fcreate&json=1

will set (update) custom field 7 to "yay" if contact 105 has previously had that field set to something, but if not I get "One of parameters (value: ) is not of the type Integer". custom_7 is not an integer field type. Looks like the UPDATE works but not the CREATE?

I'm on CiviCRM 4.0.5.

Looks buggy to me, (and Kurund + Michal couldn't figure it either!), but perhaps there's some designed reason for this?

Thanks.
Rich

[xavier]

Hi,

I know it has been changed/fixed recently. Could you check on demo? You don't seem to have the latest version of civi.

[Eileen]

Recent changes have only focussed on 'GET' , not 'create'