Links

1. Overview / Introduction

Links represent directed relationships between two lifecycled objects in the digital thread. They are foundational to model interconnectivity in SBE’s platform and are crucial for forming a coherent graph across distributed models. Each link encapsulates a source, a destination, and a relationshipName to provide semantic meaning. Though technically they can link any two objects, they are primarily used in models, starting with the Woburn release. Stored in a dedicated MongoDB collection and managed by the link-service, links do not expose public APIs; they are only accessed and governed through the lifecycles that own them.

2. Conceptual Role

Links solve the challenge of expressing cross-model associations—think requirements being verified by tests, or system diagrams referencing ports. They embody semantic connections between models and allow SBE users to trace, traverse, and manipulate the digital thread. Without links, models would be isolated entities, and cross-system interoperability would be significantly constrained. In fact, links are often considered the most important part of a model, enabling multi-tool integration.

3. Design Rationale

The design of links prioritizes lifecycle integrity and cross-context traceability. Each link is stored independently in the link-service and includes flags like isLatest, isActive, and isOwning to capture dynamic state:

• isLatest: This flag is true only for links owned by the latest version of the source model. Links belonging to earlier versions are preserved for historical context but are excluded from standard model queries.

• isActive: This flag is true only when both the source and destination models are active, i.e., not archived. If either model is archived, isActive is set to false. Inactive links are excluded from any standard GET requests, adapter refreshes, or other automated systems unless the request specifically requests to include archived models.

• isOwning: This field is governed by the link dictionary entry defined in the Link Dictionary Entry (LDE). If the relationship type for a link is marked as "owning" in the dictionary, it indicates that the source model owns the destination model. This ownership becomes especially important during subscription creation. When users request to include all owned items, the platform:

  1. Starts with the explicitly selected models.

  2. Includes links owned by those models.

  3. For any links where isOwning = true, includes the destination models.

  4. Repeats the process recursively for the newly included destination models and their owned links.

  This recursive inclusion continues until no additional owning links are discovered. It enables efficient capture of logical model groupings.

A critical aspect of link design also includes two visibility flags:

• isOutboundInContext

• isInboundInContext

These flags determine link visibility depending on the point of view:

• When a user views links from the source model’s perspective, isOutboundInContext controls visibility. It is true if the destination model is in the source’s context.

• From the destination model’s perspective, isInboundInContext is used. It is true if the source model is in the destination’s context.

These fields are always true for links within the same channel, including links between Authoritative Source of Truth (ASoT) models and their subscriptions. They may be false when links point outside of the channel’s context, such as:

• Thread-level links

• Links coped by subscribing to a model whose linked targets are outside the subscriber's context

This design enables the platform to enforce context-aware visibility while preserving link integrity.

3a. Link Projection

Link projection is an automated mechanism that ensures links maintain their semantic integrity even across context boundaries. When a user subscribes to a model that includes links whose destinations are not available in the subscriber’s context, those links are still brought over into the subscriber’s clone set, but both isOutboundInContext and isInboundInContext flags are set to false, indicating the destinations are currently out of context.

Later, if the user subscribes to the destination models, the platform automatically updates those links through the link projection system. This system listens for events when out-of-context link targets become available in the subscriber’s environment. Once available, it re-points the link from the original version to the version now present in the subscriber’s context, updating the context flags appropriately. This dynamic, event-driven capability ensures that links stay meaningful and usable even in staggered or partial subscriptions, preserving cross-model relationships seamlessly.

3b. Link Charting

Link charting is the feature in the SBE platform that backfills link destinations once they become known to the platform. This process ensures that links to external or not-yet-available destinations are automatically resolved once those destinations are introduced to the system.

For example, if a user publishes a channel with links pointing to models outside their current channel's context—such as models in other projects or even external web links—the system records these links even though the destination is unavailable at the time. These links are:

• Transformed if a mapping exists.

• Correlated to the expected destination.

• Stored both in the correlation database and the link database.

When the destination is eventually published—regardless of how much time has passed—the platform recognizes the model as being the destination of at least one uncharted link and updates the link to point to the now-available destination. This process, called link charting, ensures the destination is filled in appropriately.

Link charting occurs at the end of every publish operation for two reasons:

1. Incoming destination check: The current publish might include a model that is the destination of an earlier uncharted link.

2. Outgoing destination check: The links in the current publish may point to models in other channels already known to SBE.

This delayed execution ensures the platform has full knowledge of all transformed and saved artifacts before resolving any deferred link destinations.

4. Relationship to Other Resources

Links are not standalone—they depend on models. The source model "owns" the link, and links follow the source's lifecycle changes. During model saves or publishes, the link-service validates destinations, updates flags, and maintains relationship integrity. In subscriptions or archives, ownership (isOwning) dictates whether linked models are copied recursively. This positioning makes the link-service a behind-the-scenes orchestrator of model relationships and graph integrity.

5. Conceptual Usage Patterns

• Creation: Triggered during model edits or transformations.

• Propagation: Ownership can lead to recursive operations during subscriptions.

• Charting: A background process fills out uncharted links once their destination becomes available.

• Archiving: Links may be archived when source or destination models are archived unless explicitly carried forward.

• Context Visibility: Visibility is governed by whether the destination model is part of the source model’s context.

Typical lifecycle states:

• Uncharted: Destination unknown.

• Charted: Destination confirmed.

• Inactive: Either model archived.

• Latest: Belongs to latest source variant.

6. Common Pitfalls, Misunderstandings, and Troubleshooting

• Bidirectional links don’t exist: All links are directional and have a source and destination model (once charted).

• Context visibility: Links won't appear unless the correct context is configured, especially for thread links.

• Charting assumptions: Users may expect immediate visibility of thread links, but charting is asynchronous and dependent on system events.

• Archived links: Failing to carry forward out-of-context links during updates leads to unexpected link losses.

• Context-sensitive link deletions during refresh: If a link is not present in a UIF payload during a refresh, it will be removed from the external system. This becomes a pitfall when link visibility is constrained by the isInboundInContext or isOutboundInContext flags. For example, a thread link whose destination is outside of the source model’s context will have isOutboundInContext = false. When a user requests a refresh, that link is excluded from the UIF payload — and thus deleted from the external system. It’s critical to ensure that the appropriate context is fully configured before performing a refresh to avoid inadvertently removing thread links from downstream tools.

7. Links and Universal Item Format (UIF) Refresh Behavior

When adapters perform refresh operations using the Universal Item Format (UIF), link changes are handled implicitly, in contrast to explicit model deletion instructions. If a model is deleted, the adapter receives a specific directive to remove it. However, links behave differently: when a link is deleted or recreated in the platform, no explicit command is issued to the adapter.

Instead, when a user requests a refresh, the system transforms the current state of the model into UIF, including its existing links. Any link that was deleted simply won't appear in the resulting UIF payload. The adapter then uses this payload to reconcile state with the external system:

• Deleted links: If a link exists in the external system but not in the UIF payload, it will be removed.

• New links: If a link appears in the UIF payload but is missing from the external system, it will be added.

This ensures that adapters always apply a full, current view of the model’s link state during refresh operations, maintaining consistency without requiring explicit link-specific instructions.

8. Further Reading