Adapt the data in your endpoints

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.

Before synchronizing records between Agile Manager and ALM, adapt the data in either endpoint to match the fields supported in the other endpoint, as well as synchronization requirements.

For example, Agile Manager defects can also have a feature and theme defined. To synchronize these fields, you must create corresponding fields in ALM.

In Agile Manager, user stories are often arranged in a hierarchy, under features and themes. To synchronize these records with ALM, you must create a corresponding hierarchy of requirement types.

Modify in both ALM and Agile Manager

In both endpoints, create user-defined or custom fields to represent the record ID in the other endpoint. Define these fields as Number or Numeric fields.

  • In ALM, create a field named Agile Manager ID.
  • In Agile Manager, create a field named ALM or QC ID.

Later, map these corresponding fields in the link's Field Mapping tab. For details, see Edit field mapping.

Note: Avoid special characters (~!@#$%()^&) in attachment names, as these may cause unexpected behavior during synchronization.

Modify in ALM

Decide on ALM requirement types that represent Agile Manager themes, features, and user stories, and arrange them in a hierarchy that matches the one in Agile Manager.

  1. If needed, create new user-defined requirement types in ALM customization. Do not base new requirement types on the Folder type.

    We recommend the following: 

    • Create a new User Story requirement type in ALM to represent user stories.
    • Use ALM's out-of-the-box Functional requirement type to represent features.
    • Use the ALM's out-of-the-box Business requirement type to represent themes.

  2. Create or modify the requirement tree with a maximum of three levels (representing themes, features, and user stories). Click the image below to show an example.

    NextGen Synchronizer retains the hierarchy during synchronization.

Note:  

  • You can map only one ALM requirement type to each of these Agile Manager entity types.

  • If you do not map a specific ALM requirement type, requirements of that type are not synchronized.

  • Synchronization may fail if:

    • You do not map all requirement types, including Theme, Feature, and User Story.

    • Synchronized requirements are not located in the correct location in the ALM root hierarchy.

    • You change a requirement's type after it was synchronized.

By default, NextGen Synchronizer synchronizes:

  • the entire ALM Requirements root folder, not including sub-folders.
  • all current releases (with an end date that has not yet passed) in the ALM Releases root folder, including sub-folders.

To synchronize only a subset of the requirements or releases in your ALM project, you can specify an alternate root folder in the synchronization link.

In the ALM project's tree, create a sub-folder that contains only the requirements or releases that you want to synchronize. (For requirements, this sub-folder should not contain any sub-folders).

Note: If you also define favorites in ALM or Agile Manager to filter the synchronized records, the alternate root folder is considered first.

Example:  

In the example on the right:

  • The user stories in Agile Manager Workspace1 are synchronized with the requirements in the ALM AG_Project1 folder instead of the Requirements folder.
  • The user stories in Agile Manager Workspace2 are synchronized with the requirements in the ALM AG_Project2 folder instead of the Requirements folder.
  • In both ALM projects, other sub-folders are ignored by Synchronizer.
  • You could similarly set up an alternate root folder for releases. In that case, sub-folders would be included in the synchronization.

For details on defining the alternate root folder in your synchronization link, see Optional: Define an alternate root folder (requirement and release links).

  • If you want to synchronize past releases, determine the end date of the oldest release you want to synchronize. You specify this date on the Rules tab, when selecting the Synchronize past releases... option.

  • If you have releases or sprints/cycles with the same names defined in both ALM and Agile Manager, select the Map pairs of new releases and sprints/cycles with identical names option.

    The data from the dominant endpoint is used for all release entities, overriding any data in the other endpoint.

    Why select this option?

    If identically named releases or sprints are found and are not mapped, these releases or sprints are not synchronized at all and a "duplicate entities" error is generated in the Run Report.

    This is because Synchronizer tries to handle the release as a new record, creating it in the destination endpoint.

    The synchronization fails because the destination endpoint already has a release or sprint/cycle with the same name.

    If you later change the name of one of the releases or sprints, so that the duplication does not occur, the Synchronizer re-creates it in the destination endpoint.

    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).

    For example:

    If... Then...
    • You have a current ALM release named Release_1.3, as well as a current Agile Manager release named Release_1.3
    • You define Agile Manager as the dominant endpoint for the release link fields (in the Field Mapping tab)
    • You select the Map pairs of new releases or sprints found with identical names option in the Rules tab
    • The two releases are mapped.
    • All data in the ALM release Release_1.3 is overwritten by the data in the Agile Manager release Release_1.3.

     
    • You have:
      • An ALM release named Release_1.3, whose end date is July 20, 2015.
      • An Agile Manager release named Release_1.3. whose end date is July 30, 2015.
    • You define Agile Manager as the dominant endpoint for the release link fields (in the Field Mapping tab)
    • You select Synchronize past releases. End date can be this date or later: July 25, 2015.
    • You select the Map pairs of new releases or sprints found with identical names option in the Rules tab.

    The ALM release is not relevant for mapping, because it is too far in the past.

    However, synchronizing Release_1.3 to ALM fails because it tries to create a release on ALM with a name that already exists.

In ALM, modify the fields listed in the following table. If a field does not already exist in ALM, create a user-defined field to correspond to this data in Agile Manager. For details about mapping fields after setting up your link, see Edit field mapping.

Defining fields as Lookup List fields enables you to have empty lists, but still use this field for grouping in ALM.

Field name Description For Defects For Requirements
Application

Define as a Lookup List field.

Configure ALM not to verify this value.

Tip: Alternately, when editing your link, map the Agile Manager Application field to the ALM Product field.

If you do this, any new applications added to Agile Manager are not automatically created in ALM. To synchronize these new applications, you must first add the new Product value in ALM.

√

 √

Assigned to

 Define as a User List field. x √
Blocked Define as a String field. √ x
Bucket

Define as a Lookup List field.

Configure ALM not to verify this value.

 √ x
Feature

Define as a Lookup List field.

Configure ALM not to verify this value.

Note: This field is required if you use features and themes.

 √ x
Feature Status

Define as a Lookup List field.

Configure ALM not to verify this value.

 x √
Invested (Hours) Define as a Number field. √ x
Kanban Status Define as a String field. √ x
Rank Define as a Number field. √ √
Remaining (Hours) Define as a Number field. √ x
Story Points Define as a Number field. √ √
Story Status

Define as a Lookup List field.

Configure ALM not to verify this value.

 x √
Team

Define as a Lookup List field.

Configure ALM not to verify this value.

 √ √
Theme

Define as a Lookup List field.

Configure ALM not to verify this value.

Note: This field is required if you use features or themes.

 √ x

Tip: You may want to create an additional user-defined field to distinguish between entities created directly in ALM and those synchronized from Agile Manager.

To do so, create a field in ALM named Creation Method. Later, when you are mapping fields, assign a constant value of created by Synchronizer. For details about assigning constant values, see Edit field mapping.

Notes for themes, features, and teams

Themes and feature names must be unique in both ALM and Agile Manager, and team names must be unique in ALM. If duplicate values are found during synchronization, the related record is not synchronized.

  • In Agile Manager, a workspace team and a feature team can technically have the same name. However, this is not recommended within the same release to prevent confusion or errors when synchronizing. For details, see Notes for synchronizing team fields.

  • In Agile Manager, records assigned to a specific feature must also have a theme defined. If you synchronize features, you must also synchronize themes. Therefore, if you map theme and feature fields, we recommend making them required fields in ALM to avoid synchronization errors.

Notes about maximum record sizes

NextGen Synchronizer supports a maximum record size of 12 MB. This means that synchronizing records larger than 12 MB will cause errors.

If you have records that are larger than 12 MB, move some of the data from the Description, Comment, or any other custom free text field, to a separate file. Then, add the file to the record as an attachment. Attachment sizes are not included in the maximum record size, though they are synchronized between the endpoints.