Relationship mapping

This topic explains how to map relationships between item types and synchronize links across data sources. For basic type mappings, see Type mapping.

Overview

In addition to mapping attribute fields between types, you can also map relationship fields.

A relationship field defines the link between two types in a data source. For example, in OpenText Software Delivery Management, a story is linked to a feature by the story's Feature field.

You can synchronize those relationships between data sources. For example, you can map and synchronize the OpenText Software Delivery Management story-to-feature relationship with a similar story-to-epic relationship in Jira.

When creating a relationship mapping, consider the following:

  • The relationships in either data source may not be the same type. For example, OpenText Software Delivery Management's story-feature relationship is a parent-child relationship, whereas most relationships in Jira are many-many relationships..

  • Where there is ambiguity between relationship and attribute fields, the relationship is represented as a field with the prefix link.

    For example, in the list of Jira story fields, fixVersions is a regular attribute field populated in Jira by a plain string. The link.fixVersions field represents the story's relationship to a virtual fixVersion entity. This lets you treat Jira's fixVersions as an OpenText Software Delivery Management release.

Relationship mapping in Azure DevOps

You can synchronize Azure DevOps work items with customized relationships directly from the user interface.

To create a relationship:

  1. In Azure DevOps, create a custom relation.

  2. Navigate to the Data Sources tab and select an Azure DevOps data source.

  3. Navigate to the Relationships tab and click + Relationship.

  4. Add the custom relation that you created in Azure DevOps.

  5. Navigate to the Connections tab and create a connection or open an existing one for editing.

  6. In the Types and Fields section of the Features pane, add a custom relationship to the field mapping.

  7. Add data to the Azure DevOps data source and run a test iteration.

Child link mappings

Mapping links (relationships) between items from one endpoint type to another is supported, provided that the item types are mapped. For example, to synchronize OpenText Application Quality Management defect Release and Release Cycle links with Jira Release and Sprint links, you must map the Release to Release and the Release Cycle to Sprint types in that connection.

In most cases, the default behavior of this mapping updates or creates the desired fields. Consider the architectural differences of the endpoint types. For example, unlike OpenText Application Quality Management, Jira sprints are not linked to Jira releases. In addition, in Jira, start and end dates are not mandatory fields.

If you do not want to synchronize the parent types, such as sprints, releases, release cycles, and iterations, but you do want to synchronize links for child types, such as defects, bugs, or requirements, map by name, or map the type manually, as described below.

Map by name

Map by name incorporates custom utilities to map the OpenText applications to Jira and Azure DevOps.

For this method, create fields such as sprints, releases, or release cycles on the endpoint systems in the relevant projects. Make sure the field names are identical because they are case-sensitive.

These utilities run directly on the endpoint systems and perform the following steps:

  1. Query the database and find the supported types in all projects in all running connections.

  2. Match the entities of these types by name.

  3. Retrieve the IDs and write them into the database as cross references.

These utilities can be integrated into a nightly purge script so that they run when the Connect service is down. This serves as a scheduled catch-up for changes made to matching artifacts. For information about the utilities, contact support.

Manually map

Manual mapping is an alternative method that the system configuration admin can deploy. With this strategy, names are not used.

To manually map the items, admins should perform the following steps

  1. Determine the matching values, for example the Jira Release that corresponds to the OpenText Application Quality Management Release, and the Jira sprint that matches the OpenText application's release cycle.

  2. Import or insert the cross references as <adds> pairs directly into the database. For details, see Edit and import cross reference files.

Best practices

To ensure the success of the mapping methods described above, suspend synchronization while mapping the types. For example, map the OpenText Release type to the Jira Release type, and the Release Cycle type to the Jira Sprint type, but explicitly exclude all of the types' properties.

Mapping types without properties allows cross references to load the types from the database without creating or updating artifacts on either side. This approach allows control at the connection level.

Alternatively, set the type to ReadOnly at the data source level. However, this affects all connections associated with the data source.

Note: When mapping links using calculated values, use the FindFirst function to set a value.

For example, do not set a calculated value using this syntax:

set Release = 123456

Instead, use the following syntax:

set Release = FindFirst(Release) where ID equals 123456

For details, see Functions.

See also