Synchronizing Relationships

Synchronizing Relationships 

Hub affords you the ability to not only flow various artifacts between your collections, but also to mirror the relationships between those artifacts. This is referred to as Artifact Relationship Management (ARM). There are two types of ARM: Internal ARM and External ARM. We will outline both types below.

Synchronizing Internal Relationships

Below, we'll outline an Internal ARM scenario where we flow Microsoft TFS features to Jira epics, in addition to the defects that block themall while preserving the relationships between the artifacts within each internal system.

Internal ARM

Here's how to configure this scenario in Hub:

(lightbulb) First, confirm that both repositories support relationships in our Connector Documentation.

  1. To flow these artifacts along with their relationships, we will need to configure two integrations (and four collections):
    1. Microsoft TFS Features ↔ Jira Epics, with 'blocked by' relationship field mapping
    2. Microsoft TFS Defects ↔ Jira Defects 
  2. First, configure your Feature ↔ Epics Synchronize Integration
    1. Ensure that your model includes a 'blocked by' relationships field
      1. (lightbulb) In general, we recommend using the 'relationships' field type in your model, rather than 'relationship,' especially in cases where you may want to map a 'relationship' field in one repository to a 'relationships' field in your other repository.
    2. On each Collection, click 'configure relationship types,' and map the 'blocked by' model field to the appropriate relationship field ('affected by' in TFS and 'is blocked by' in Jira).
    3. On the Field Flow screen, you will see the two relationship types mapped to one another.
    Internal ARM Field Flow
  3. Next, configure your Defect ↔ Defect Synchronize Integration as you normally would.
  4. Run both integrations. You will see your epics and features, and your defects, as well as their relationships to one another successfully flow as part of your integration.

(lightbulb) Note: If you are configuring an integration between different collections of the same repository (i.e., to flow artifacts from one project in Jira to another project in Jira), the best practice is to create two separate repository connections in Hub for the source repository and the target repository. This will eliminate errors encountered in Hub related to relationship fields.

Synchronizing External Relationships

If you'd like a more lightweight approach, you can configure the scenario below to flow the URL of the related artifact in the source repository to a weblink or string field in the target repository. This is what we refer to as External ARM (Artifact Relationship Management).

External ARM

Both internal ARM and external ARM are configured the same way with regard to the source collection: A relationship field in the source collection is mapped to a relationship field in the model.

The crucial difference is how the target collection is configured:

  • For internal ARM, that relationship field in the model is then mapped to a relationship field in the target collection.
  • For external ARM, that relationship field in the model is then mapped to a string field or weblink field in the target collection.

Internal ARM Configuration vs. External ARM Configuration

To configure External ARM in Hub, follow the instructions below:

(lightbulb) First, confirm that both repositories support the following in our Connector Documentation:

For the source repository:

  • Relationship field types are supported
  • The related artifact type (whose URL you would like to flow) is supported, and provides a unique URL

For the target repository:

  • String fields or weblink fields are supported


  1. Here, our goal will be similar to the goal in the Internal ARM section: to flow Microsoft TFS Features to Jira Epics. For any TFS Features that have related TFS Defects, instead of creating a related defect in Jira, we'd like to flow the URL for each defect to a custom string field on the Jira Epic.
  2. In this scenario, we will only configure 2 collections (Microsoft TFS Features and Jira Epics), and 1 integration (Microsoft TFS Features → Jira Epics), in contrast to the internal ARM scenario, which required two integrations. A second integration is not needed here, because we are not creating target defects in Jira.  Rather, we are flowing the URL of the source defect to a custom field on the Jira Epic.
  3. To configure this scenario, create a synchronize integration for your main artifact type.  
    1. In this example, we will flow Microsoft TFS Features to Jira Epics.
  4. On the source collection (Microsoft TFS Features), configure a relationship mapping for the relationship type you'd like to flow.
    1. In this example, we will map "Affected by" relationship field to our 'blocked by' relationship field in the model.
  5. On the target collection (Jira Epics), configure a mapping between the string or weblink field that you'd like to receive the URL, and the relationship field in the model that was mapped in the prior step.
    1. In this example, we will map the Jira custom string field, "TFS Defects" to the "blocked' relationship field in the model.
  6. You'll see that your field flow for the integration looks like this:
    External ARM Field Flow
  7. When we run our integration, we will see that Microsoft TFS Features create Epics in Jira, AND that the related defects in Microsoft TFS flow their URLs to the Web Links field on the Jira Epic.