Proposal - make future recurring contribution instances modifiable & not fail if the only contribution is deleted.

Currently each contribution in a recurring contribution series is generated based on the most recent completed contribution in that series. In some cases there is a desire to alter it as time goes on - with requests to change

• line items
• custom fields
• soft credits
• link to the contribution page
• campaign

We also see issues where the only contribution stored against it is deleted & the contribution fails - either by a site users or in Sepa's case an attempt to change the workings.

At Barcelona we discussed this and decided that from a data model point of view we would

• Add an is_template field to the civicrm_contribution table - added in 5.20
• Update CRM_Contribute_BAO_ContributionRecur::getTemplateContribution (with test) to attempt to first attempt to retrieve the latest template contribution associated with a recurring contribution and failing that to default back to the latest contribution done in 5.20
• Update apiv4 to not return is_template entities (for any entity) by default~~ done with test in 5.20
• update apiv3 to not return is_template contributions by default PR in 5.20
• update civicrm search to not return is_template contributions by default (todo)
• update civicrm reports to not return is_template contributions by default (todo)
• to reduce risk of leakage ALSO add a new contribution status 'TEMPLATE' so that places that do not implement one of the above are still unlikely to get them. Added in this pr
• filter the new status from the various forms so people can't change status to it in this PR and this PR
• UI testing to make sure the new status doesn't leak
• Add code in CRM_Contribute_BAO_Contribution that makes is so setting is_template on a contribution ALSO sets the status
• Consider adding code (in an extension - in the first instance) so that if the only contribution on a recurring contribution is deleted it is converted to a template instead.
• More UI testing to ensure template contributions don't leak
• Look at accepting template_id or similar as a parameter to Order.create, move to make it the replacement for Contribution.repeattransaction
• Consider whether we should respect recur overrides for template contributions. I think a case could be made for template overrides (those stored in civicrm_contribution_recur) to be ignored if a template contribution exists as they are really a work around not having a template contribution & the code is new at the moment so we can make new rules
• Look at a way to clone & save a contribution to a template contribution (this is kind of out of scope in round one but might not be that hard using copyGeneric - it would be an apiv4 feature)

Things we considered when evaluating the approach

1. there is already precedent for is_template on events
2. there is no move initially to create any is_template contributions in core - this gives us time for people to use it in an opt-in manner & to find & eliminate any leakage.
3. there was some discussion about whether the loss of sequentiality matters but it was decided the presence of is_test already denoted that as not being an intended architectural feature of the table and that the invoice_number field had already been added to allow sites to manage this. Jamie pointed out (below) that the status of Void / Cancelled could be used to exclude is_test so we just have another status to exclude here.
4. the key challenge was tracking custom data to copy - there was really no reasonable way of getting around tracking this without the entity_id being for a row in the civicrm_contribution table.
5. a phased approach - we wanted to set up the ground work but not impose any change in this phase.
6. it might be that we also need to add the field to other tables or to suppress entities related to an is_template contribution - probably an open investigation / discussion
7. potentially this could supercede permitting template overrides in civicrm_contribution_recur
8. the reason we've always backed out of this approach before is that it would be hugely risky to create the data structure AND start creating template contributions at once. In Barcelona we agreed NOT to start putting data in it in core in the short term & dig out all the leakage before we consider using it in core - e.g any UI features, allowing save as template. Unless extension writers take action no template contributions will exist

Previous JIRA CRM-13839