Declaration types

I have to say that this idea rather blows my mind😃. It feels like each "use case" or "scenario" ends up with both a declaration type and an evidence type. Some concepts/fields already on evidence type are duplicated onto declaration type. Sometimes the declaration/evidence will only make sense in the particular pairings, other times it could be more flexible but at least an oral declaration should have an oral evidence type.

I feel that your IS is written from the perspective that the "no declaration type" option is hard, however I'd like to explore the problems you present:

1. Not necessarily "quite a few fields" but one field about allowable use cases (declare/cancel/CoA) should be enough. Is it hard to understand? For each specific paper form there would be an evidence type. Seeing as the forms are reasonably examples of evidence then it isn't necessarily so bad. Telephone and in person seem to work well. The evidence types could be re-used for change of address or cancellation. I feel it's harder to understand the "declaration types and evidence types" system, because the poor admin has to create both entities. And some of the evidence types could end up anyway being specific to declarations only, so it's almost like the worst of both worlds.

2) Yes there would need to be some restrictions. But it's likely not as bad as the restrictions needed if we have both declaration and evidence types.

3) Declarations would generally have just one evidence I expect. HMRC are clear I believe - any change should be a new declaration. Editing is only allowed for corrections.

I see a real problem with your scenario different from the above 3. In various ways you would like the evidence types to influence fields that are actually present on the declaration.

1. In case of the paper forms, you would like to hard-code a value for explanation (set a default and hide the field). The evidence type currently doesn't allow this because that field is on declaration.
2. You would like the evidence type to influence whether confirmation is required. Actually it can already via the method field. Web = no, oral = yes, written = maybe. But perhaps you'd like more flexibility: a written format that definitely requires confirmation or any staff format that definitely doesn't etc. This has a fairly easy solution: we could change the method field to "written confirmation required" with values yes/no/maybe.
3. You would like the evidence type to influence validity and start date - which are declaration fields.

If we are going to have declaration types then potentially we should remove the evidence entity, or at least stop using it for declarations. This is going to be a fairly large piece of work.

I'm seeing a lot of value of (multiple) evidence entities, even in the context of declarations:
- as discussed in 📌 Change handling of web evidence Active it's a nice way to generically store audit information about a web submission, such as the explanation given
- it's a nice place to store details of any written confirmation sent (when, to where, what wording)

For clarity:
what I'm suggesting is that a declaration would still have an evidence field, but we'd label it "Additional evidence". The declaration type fields would handle the main original evidence for that declaration, the evidence field would handle supplementary stuff. The declaration add form woudn't even need to show the evidence field.

Not necessarily "quite a few fields" but one field about allowable use cases (declare/cancel/CoA) should be enough.

I take your point, a set of checkboxes for use cases would work.
If they checked the "declare" use case then there'd need to be a show/hide #states on a second setting about whether written confirmation is always/never.

I retract my point #1 entirely; I'm not sure if it's an easier or harder mental model but it's OK either way and sitebuilders aren't a priority in some sense.

I don't think it's harder having declaration types because I think most sites will be happy with just 3 simple evidence types (for cancel/COA/misc) that we could provide OOTB (email, document (pdf/image), and oral). It's declaration types that I'm seeing a lot more likelihood for sites to want to make custom flavours of as they will be much more heavily used.

2. Using the current IEF widget would be hard. We'd need to restrict it to just this subset of evidence types when creating a declaration; and even then the current dropbutton only shows the label and doesn't allow for a description. Likely we'd need to cobble together a non-standard UI to require staff to select one of these when creating a declaration. That could be a selection page followed by a querystring param that's interpreted in the declaration form, or it could be a customisation of the IEF widget or some custom widget.

Yes there would need to be some restrictions. But it's likely not as bad as the restrictions needed if we have both declaration and evidence types.

This UX problem is the big one for me.

Regarding the restrictions, there's no problem if declaration and evidence type is seperate. We would then have a declaration "add page" where you select the type first, no need to involve evidence types.

The worse problem is how we show a bundle description to the user if we're just using an IEF. Customising IEFs gets hairy fast.

In various ways you would like the evidence types to influence fields that are actually present on the declaration.

Exactly. Which is why it feels more natural to me for this to be the "declaration type" that is influencing the declaration fields. If we only had one piece of evidence per declaration this'd be less of an issue, but for reasons given above and below I think it's valuable to retain the possibility of multiple.

If we are going to have declaration types then potentially we should remove the evidence entity, or at least stop using it for declarations

I like the evidence entity, for the reasons given above. It does a great job of handling edge cases and weirdness because it's s flexible. It's just slightly weaker at creating simple well-trodden pathways for the main everyday staff scenarios.

Declarations would generally have just one evidence I expect. HMRC are clear I believe - any change should be a new declaration. Editing is only allowed for corrections.

Allowing multiple pieces of evidence on an entity does a good job of handling weird edge cases. Imagine if a declaration gets given as part of an email conversation with a donor - when is that conversation completely over? What if the donor sends another clarifying email? What if a form is hard to read so it gets scanned a second time for improved legibility? etc. What if staff email a donor to check something with them because they couldn't quite read a form? etc

Your evidence system is wonderfully flexible and I'm keen to keep that.

=============

TLDR;
the choice is between either
(1) Do some funky work to make it work with evidence types:
(a) either (i) have a custom IEF widget, limited to 'declare' use cases evidence types and showing description as well as label; or (ii) have an evidence type select page (like a normal entity type add page) before the declaration form and use that to preselect the evidence type open in the IEF simple widget in the declaration form.
(b) use that first piece of evidence as the key 'type' of the declaration for influencing other fields and make sure we only care about that when the declaration is first submitted, make sure we don't need or depend on that after that in case the evidence gets messed with by an admin.

(2) Add declaration types, with a declaration add page to select the declararion type before the declaration form. The declaration types do overlap somewhat with evidence types, but everything else about them is straightforward idiomatic Drupal.

Either approach works. My suspicion is that (2) is easier.

I can see why for us, thinking about the concept of evidence in the context of the HMRC guidance, it seems weird to have evidence stored in these two places. But this distinction also corresponds with an important one in practice:
- 95% of the time staff would use the system just add declarations in a simple way
- dealing with other "evidence" would only come up in much rarer circumstances (my organisation basically almost never deals with COA or cancel evidence in practice).

We are in agreement that the declaration can have multiple evidence, but it's an edge case.

The declaration add form wouldn't even need to show the evidence field.

OK that removes many of my concerns. Still, this is a fair chunk of work. We need to add the declaration types (which we had the code before, so just finding it), create some default entity config and write code for the "add declaration" page for choosing the type. We need to move a few fields around, and adjust both pieces of code that generate web based declarations and adjust the corresponding tests.

as discussed in #3534245: Change handling of web evidence it's a nice way to generically store audit information about a web submission, such as the explanation given

Surely if we are having declaration types, then we no longer need web evidence?? We would have web declaration types instead. I don't see how the "supplementary evidence" on a declaration can ever really be web (self-declared) - it would always be staff.

Surely if we are having declaration types, then we no longer need web evidence

Fair point.

We might want it anyway for cancellation and COA?

Thanks for all your engagement in this. I definitely made a few mistakes in my thinking along the way that you've cleared up.

In #3 I wrote

In various ways you would like the evidence types to influence fields that are actually present on the declaration.

We realised that even if we change to declaration types, then we still can't set a per-bundle default to base fields. Instead we would need to add properties on the declaration type, with logic (perhaps on pre-create) that uses those properties to set field defaults.

It just occurred to me, if we are doing that, we could equally well put the properties on the evidence type. So to revisit the TLDR of #4, we need 2 bits of "funky work", whether or not we have declaration types.

1) A mechanism for selecting bundle type (applies to either/both of evidence/declaration) - either a new page, or an enhanced select widget. We would prefer to show descriptions as well as labels. We might like to filter out some values (already we filter out the web ones).

2) A mechanism for setting default declaration field values based on the bundle type (either evidence or declaration).

In addition there are some further work items

3) Add declaration types

4) Alter some declaration fields, converting multi-state values to multiple booleans

It just occurred to me, if we are doing that, we could equally well put the properties on the evidence type. So to revisit the TLDR of #4, we need 2 bits of "funky work", whether or not we have declaration types.

I take your point, but I still lean in favour of declaration types.