Towards CRM-21140, support at api level for custom data on any entity.

[eileenmcnaughton]

Overview

This extends the ability to support additional entities for custom data by
adding them to the OptionGroup 'cg_extends'. At this stage there
are 2 additional tested (supported) entities - UFGroup, PriceSet, PaymentToken.

Note this 'feature' is expected to be available for the March release (5.0.0.0 I think) so that extension writers can target 5.x for custom data on any entity. This is just progress towards that goal

Will add more next iteration

Before

Not possible to extend entities for custom data outside hard-coded core ones.

After

UFGroup, PriceSet, PaymentToken now possible & tested/supported.

Technical Details

Comments

I will follow up with the next ones I can test later

---

• CRM-21140: Agree & (if applicable) implement approach to storing extension data for entities / tables

[eileenmcnaughton]

@MegaphoneJon - any chance you can review this? It's actually a pretty trivial change due to past clean up we have done

[MegaphoneJon]

Yes, I had my eye on it! I've been slammed but I have a need for this, so I'll make some time in the next couple of days.

[MegaphoneJon]

This looks good! I was even able to test this through the UI with a little bit of trickery, using an entity not covered by the unit tests. I feel good about this.

[MegaphoneJon]

(CiviCRM Review Template DEL-1.0)

• JIRA (r-jira)
  • PASS : The PR has a JIRA reference.
• Test results (r-test)
  • PASS: The test results are all-clear.
• Code quality (r-code)
  • PASS: The functionality, purpose, and style of the code seems clear+sensible.
• Documentation (r-doc)
  • ISSUE: The developer documentation should be updated.
  • COMMENTS: This should probably be a separate PR against the docs, and shouldn't prevent a merge. It might also be desirable to wait until there's a UI interface for this if one is planned (it would be very simple to create).
• Maintainability (r-maint)
  • PASS: The change sufficiently improves test coverage, or the change is trivial enough that it does not require tests.
• Run it (r-run)
  • PASS: In addition to running the automated tests, I implemented custom fields on "Financial Type" through the UI. I went to Administer » System Settings » Option Groups, edited the "cg_extends_objects" option group, and entered civicrm_financial_type as a label and FinancialType as a value. Once saved, I changed the label to Financial Type. This changed the label, but the name stayed as civicrm_financial type. Once this was done, I created a new custom group/field and was able to successfully add values to it (for both new and existing records) using FinancialType.create. I could query them successfully using FinancialType.get.
• User impact (r-user)
  • PASS: The change would be intuitive or unnoticeable for a majority of users who work with this feature.
  • COMMENTS: This is a new feature, so shouldn't be noticeable except when creating new custom field groups, where the change is intuitive.
• Technical impact (r-tech)
  • PASS: The change preserves compatibility with existing callers/code/downstream.
  • COMMENTS: The changed function returns a superset of the values returned by the original function, so this won't cause problems for existing code.

[eileenmcnaughton]

@colemanw are you ok to merge this based on @MegaphoneJon review.

Re additional entities - I do plan to chip away at adding them to the unit tests & confirm which others do / don't work. I specifically know the mailing api needs some clean up first (because it does weird stuff with the deprecated $ids parameter.

I will follow up with the docs pr once this is merged

[colemanw]

Ok, so my understanding is that with this PR we now have 2 approaches to custom data:

1. Handle it at the BAO level. Most entities do this.
2. Handle it at the api level.

Is the goal to eventually consolidate on the 2nd approach?

How does this affect the custom data UI? Wouldn't we want additions to that option group to affect this list?

[eileenmcnaughton]

@colemanw - there is no intention at this stage to expose the new options through the UI - that can be up to extension writers to do that as they add functionality.

Regarding the BAO vs api - I think it would be ideal to consolidate on the api but this approach succeeds in at least not doubling up - ie. where it is already through the BAO we are not doing it twice since we have an array of those entities. It's hard to remove from the BAO without ensuring there are no places relying on it

[colemanw]

How would an extension go about altering that UI? My assumption as a developer would be that adding an entity to that option group would also add it to the list in the UI, but if there is another relatively straightforward way of doing it, ok.

[eileenmcnaughton]

Actually I guess that UI might pick it up - I'm not sure how it builds it - at this stage I'm focussed on the scenario where developers want to create additional custom fields against entities in extensions - rather than allowing people to add them themselves.

I guess if an entity is enabled for custom data & that entity happens to be enabled in the UI then it's probably OK - but I wouldn't have tried to add that purposely at this stage. I think stage one is that developers can add custom fields against any entity, including ones that they create themselves.

[MegaphoneJon]

To respond to the question above: Any entities added to the cg_extend_objects OptionGroup WILL show up in the UI in the select box that Coleman screenshot above. In fact "Cases" and "Survey" in that list are generated from the option group.

In fact, during my testing I created custom fields for FinancialType records entirely from the UI. I needed the API to populate/read the values of course - but I was able to extend custom fields to a new entity without the API.

[colemanw]

Ok, very cool.