Using linked_items_urns in effects

[aduane]

Discussed in #344

^{Originally posted by andhines January 17, 2025}
It's unclear where these urns come from, or how I as a plugin developer can discover and select them to then set in the linked_items_urns field of the task command.

In order for effects (Create Task in particular) to link related items, we must be able to derive their URN. These are not stored anywhere, so we'll have to calculate them. Another caveat is that while many object classes can have linked URNs, not all classes can accept just any URNs from any class. (Not all object types can be linked together, for example, Tasks have a specific set of other object types that can be linked to).

The way we would implement this is to define a get_v1_urn method on the data module classes that can be linked to, and also define an add_linked_item method on the effect that can accept these links. The add_linked_item method would raise if a class type was added that is not supported for linking. When the effect is applied, we call get_v1_urn on each of the items in the linked items list.

Example:

class SomeEffect:
    linked_items: list[<type1> | <type2>]
    def add_linked_item(self, item: <type1> | <type2>):
        <check item type, raise if not an allowed type>
        self.linked_items.append(item)

    def apply(self) -> Effect:
        linked_urns = <iterate over linked items and call `get_v1_urn` on each>
        return Effect(payload: {linked_urns: linked_urns})