Add test for attaching aspect to a different element

[jackson-at-bentley]

Hey core team. I'm working on aspect support in the declarative connector framework @itwin/pcf. The aspect API gave me a hard time with my declarative synchronizer fir and I suspect @itwin/connector-framework is going to run into the same problems when it eventually supports aspects.

This may be the same problem as #3969: currently the aspect API doesn't give you a handle on the aspect you insert, and it's just gone forever in the iModel, because aspects don't have codes or provenance.

It seems like updateAspect fails when you change the Element navigation property of its argument, which has type RelatedElementProps. In the attached test, the backend seems to consider its updated argument a different aspect even though it has the same ECInstanceId.

I'm confused and will appreciate any insight. My workaround to this in pcf is just to delete and reinsert the aspect.

[jackson-at-bentley]

Sorry Paul the CI got upset with me when I didn't include one last time.

[pmconne]

I think the premise "should be able to change the element to which an aspect attaches" is flawed. @swwilson-bsi does it make sense to talk about taking an existing aspect and relocating it to a different element?

[pmconne]

Sorry Paul the CI got upset with me when I didn't include one last time.

No worries - you still gotta run rush change, just enter an empty string for changes uninteresting to end users.

[jackson-at-bentley]

I haven't had problems changing the navigation properties (e.g., Parent) of elements when using updateElement so I thought updateAspect would behave the same. But I don't understand the implementation of aspects so this is from the perspective of an API consumer.

[swwilson-bsi]

The call to updateAspect threw a NotFound error, right? That is because the boats element does not have that aspect.

Continuing with Paul's point, an aspect is like an optional property of an element. An element has one or more aspects. Just as you don't "move" a property from one element to another, you don't "move" an aspect either.

It may be a little confusing because an ECRelationship is used to connect an aspect to its owning element. Note that the ElementOwnsUniqueUniqueAspect ECRelationship has "embedding" strength. (Ditto for ElementOwnsMultiAspects.) That means that an element aspect is conceptually part of the element that owns it.

An aspect's identity is best thought of as the ID of the owning element, plus the aspect's ECClassId. That is why insertAspect does not return the the internal ecinstanceid of the aspect. I think the BIS core docs could be a little clearer on that point. The backend API docs are a little clearer.

At a mechanical level, I can understand why one might think of moving an aspect from one element to another. But there is no API for that. You'd have call deleteAspect on the harbor and then insertAspect on the boats.

A connector that updates aspects must look them up on the owning element by ECClassId. If the source repository has changed such that a certain BIS element should no longer have a given aspect, then the connector must call deleteAspect, identifying that element. If some other BIS element should have a similar aspect, then the connect must call insertAspect, identifying that other element.

Do you think the BIS core docs should be expanded to make this clearer? Are we missing some overview docs? @diegoalexdiaz

[diegoalexdiaz]

Thanks for bringing up the need for more clarity on the article about element-aspects, @swwilson-bsi. We'll improve it for the next round of enhancements for the BIS guide.

[jackson-at-bentley]

Closing as a misunderstanding, thank you all for helping me understand how aspects are identified in the backend. I especially appreciate the advice for implementing connectors from Sam. I do still think the private ID of bis:ElementMultiAspect should be exposed by the API (because how else is updateAspect supposed to work with bis:ElementMultiAspect?).

I think Sam's linked section is clear. I didn't read it closely enough to realize that changing the Element navigation property identifies a different aspect.

It's the same situation for link-table relationships and updateInstance. Changing the source, target, or class identifies a different relationship.

So updateAspect and updateInstance are only for updating properties, not navigation properties.