Create a synchronization link

Note: This topic is relevant for NextGen Synchronizer only. For details about the ALM Synchronizer, see ALM Synchronizer for Agile Manager or search using the ALM Synchronizer filter.

After Agile Manager identifies the bridge you installed on the Integrations > Synchronizer configuration page, click Configure synchronization links.

The Add Link wizard opens automatically for you to add your first link. You can also access this wizard later on to add additional links. Select a bridge on the left, and click Add Link.

Use the wizard to configure your link. The order of the steps may vary, depending on the type of entity synchronized over this link (defects, requirements, or releases).

  1. Define a name for your link, and an optional description.

  2. Select the type of entity synchronized over this link (defects, requirements, or releases).

  3. If you work with multiple workspaces, select the workspace you want to synchronize with ALM.

    If you do not see your workspace in the drop-down list, make sure you are defined as an Integration Administrator in this workspace. For details, see Integration Administrator user.

  4. Select Existing ALM/QC Connection and select a previously defined endpoint, or select New ALM/QC Connection, and populate the following fields:

    Field Description
    ALM/QC Server URL

    URL to the ALM deployment that hosts the project you want to synchronize with.

    Use the following syntax:

    http(s)://<hostname>:<port>/qcbin
    Endpoint Display Name

    Identifies this connection to ALM.

    Tip: Assign this name when creating a new link. If you later select Existing ALM Connection to create additional links to this ALM project, you can select this display name from the list.
    Credentials Display Name

    Select a predefined credentials record from the dropdown list.

    These records are defined in the Endpoint Credentials Manager. For details, see Manage connection setup.

    You must define ALM credentials before creating a synchronization link.
    ALM/QC Domain
    ALM/QC Project

    The ALM domain and project you want to synchronize with.

    1. Click Authenticate next to the User Credentials Name field to retrieve values for these fields.
    2. Select the ALM domain and project names from the listed items.

  5. Click Check Connectivity and Continue.

Specify the ALM/QC requirement types that match user stories, features, and themes, according to the hierarchy that you defined in advance in ALM. For details on setting up this hierarchy, see Modify in ALM.

Only mapped requirement types are synchronized.

Select where you plan to manage your releases, defects, and different types of requirements. For examples on when you might select the different options, see Sample use cases.

Caution: Agile Manager does not support custom release fields.

For releases, Synchronized data includes:

  • Releases: Names, start and end dates, descriptions, and attachments.
  • Sprints/cycles: Names, start and end dates.

If you have custom release fields that are mandatory in ALM, synchronize release data only from ALM to Agile Manager, and not from Agile Manager to ALM.

  • Select one of the following:

    Option Description
    Agile Manager

    Select this option to create defects, requirements, or releases in Agile Manager only.
    During synchronization, corresponding entities are created automatically on ALM.
    Updates made to existing entities in either endpoint are synchronized with the other endpoint.

    For requirement links: This option means that you manage the entity's hierarchy (theme > feature > user story) in Agile Manager. Changes that you make to the structure of your requirements tree in ALM will be reverted by the synchronization.

    ALM

    Select this option to create defects, requirements, or releases in ALM only.
    During synchronization, corresponding entities are created automatically on Agile Manager.
    Updates made to existing entities in either endpoint are synchronized with the other endpoint.

    For requirement links: This option means that you manage the structure of your requirements tree in ALM. Changes that you make to the entity's hierarchy (theme > feature > user story) in Agile Manager will be reverted by the synchronization.

    Both Agile Manager and ALM

    (Defect and release links)

    Select this option to create and update defects or releases in both Agile Manager and ALM, for a full range of planning and testing functionality. Changes made in either endpoint are synchronized with the other endpoint.

    Note: If you select Both.., you also need to select a dominant side, in case of conflicts.

  • When you synchronize a release, all related Agile Manager sprints are synchronized with cycles in ALM.

    For a release link, select the endpoint to use as the dominant side for sprint and cycle synchronization, in case of conflicts.

You can view the rules in more detail after you create the synchronization link, and adjust them if necessary, in the link configuration Rules tab.

You can limit the synchronization to a subset of your ALM or Agile Manager database by using Agile Manager and ALM favorites.

Tip: For requirement links, you can also use an alternate root folder for a similar purpose. If you define both favorites and an alternate root folder, the alternate root folder is considered first.

Define favorites to use as filters for new items when synchronizing between endpoints. For details, see Create Agile Manager and ALM favorites.

No favorites are defined by default. This means that all records in the Agile Manager workspace or ALM project are synchronized.

Tip: Favorites are specifically useful when first configuring your link. Start by using a favorite that contains only one record, and expand it slowly. Run simulation synchronizations to verify that the synchronization works as you expect.

Remember to schedule a full synchronization each time you modify a favorite in order synchronize the newly included records. For details, see Full synchronizations.

Caution:  

  • Once a record in one endpoint is mapped to a record in the other endpoint, these records continue to be synchronized even if they no longer match the link's favorite. Be sure that you want to synchronize data in a specific record or type of record before including it in your favorite.
  • When a new requirement is created in the master endpoint, and the requirement is the child of requirements that were not previously synchronized, the parent requirements are also created in the other endpoint. If a favorite is defined, the parent requirements are synchronized even if they do not match the favorite.

You can limit the synchronization to a subset of your ALM database by selecting an alternate ALM root folder.

Select Use an alternate root folder and enter the path to a sub folder in your ALM project's Requirements or Releases folder.

The path must replicate the exact hierarchy in ALM starting with the Requirements or Releases folder, according to the ALM locale. For example: Requirements\MyProject.

Note: For a requirement link, if you define both favorites and an alternate root folder, the alternate root folder is considered first.

Caution:  

  • Make sure the folder that you enter already exists in your ALM folder structure.

  • Specifying an alternate root folder for synchronization can cause unexpected behavior.

    If you reorganize the Requirements or Releases module in ALM after having run a synchronization task, carefully move the records while retaining the same hierarchy to retain the synchronization. Do not delete records and create new ones in the new location, as Synchronizer recognizes records according to their ALM ID.

    When you move records, make sure to retain the same hierarchy as is defined for the link in Synchronizer.

  • If you move a record out of the alternate root folder in ALM, this record is no longer synchronized with Agile Manager.

    However, if you move a release out of the alternate root folder, the release is no longer synchronized, but its cycles are still synchronized.

  • You can change the path to the alternate root folder before you run the first successful synchronization for the link. Afterward, edit this path only if the folder in ALM was renamed. Do not enter a different alternate root folder.

  • Select Synchronize past releases... if you want to synchronize releases whose end date is in the past. By default, NextGen Synchronizer synchronizes only current releases.

    If you select this option, enter a date to prevent synchronizing old releases that you do not need. This date cannot be in the future.

    Agile Manager or ALM releases with an earlier end date are not synchronized.

  • Select Map pairs of new releases and sprints/cycles with identical names if you want to use data from the dominant endpoint for all fields of the identically named release or sprint/cycle in the other endpoint.

    If you do not select this option, the pairs of identically named release or sprints/cycles is not synchronized at all. A "duplicate entities" error is generated in the run report.

    Note: When mapping, NextGen Synchronizer checks only the releases that are included in the synchronized time frame. Releases or sprints/cycles with identical names are not mapped if they are in a past release (or a release whose end date is older than the one you specified for synchronization).

Click Next to complete the wizard, and then Finish to create the link.

The new link appears in the navigation tree on the left of the Link Configuration page.

If you created a requirement synchronization link, the tree includes one node for the general link settings, and additional sub-nodes for each mapped requirement type.

Next steps

When you are finished creating your link, do the following:

For details about the Run History tab, see View the run history for a specific link.

See also: