Note: This topic is relevant for ALM Synchronizer for Agile Manager only. For details about the NextGen Synchronizer see NextGen Synchronizer, or search using the NextGen Synchronizer filter.
If you are still using ALM Synchronizer, we recommend migrating to the more robust NextGen Synchronizer embedded in Agile Manager's configuration area.
To view user stories in ALM as requirements, you must synchronize them between Agile Manager and ALM. Themes and features you create in Agile Manager are also synchronized as requirements in ALM.
Before you begin to synchronize requirements (including user stories, themes or features), you must modify your ALM project with additional requirement types in a specific hierarchy. For details, see Adapt your ALM project.
After creating a new link and selecting the requirements entity type, define other link properties, such as filter options, rules, and field mapping, as described in Configure link properties and Map endpoint fields.
Specifically, define whether ALM or Agile Manager is the Master for the link. The Master endpoint is the endpoint that defines both the structure of your requirements tree in ALM, and similarly, the themes and features of a specific user story in Agile Manager.
By default, Synchronizer synchronizes all requirements in the ALM Requirements root folder. Specify an alternate root folder to synchronize only a subset of the requirements in your ALM project.
Note: If you specify an alternate root folder, ensure that other workspaces in your Agile Manager site do not synchronize with other root folders in the same ALM project.
Example: In the example illustrated
- 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.
Guidelines for specifying an alternate root folder
Specifying an alternate root folder for synchronization can cause unexpected behavior.
Consider the following:
The path to the alternate folder defined in Synchronizer must replicate the exact hierarchy in ALM. For example: Requirements\MyProject. Note that when defining this folder, the Requirements folder is already defined for you in the dialog box path.
If you reorganize the Requirements 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.
Each new requirement type in ALM can be mapped only once, to either theme, features, or user stories in Agile Manager.
If you do not map a specific ALM requirement type, requirements of that type are not synchronized.
For each mapped pair, you can only define one endpoint as a source for newly created requirements. For example, if you manage your requirements as user stories in Agile Manager, new records created in Agile Manager will be synchronized to ALM, but new records created in ALM will not be synchronized to Agile Manager.
Synchronization fails if synchronized requirements are not located in the correct location in the ALM root hierarchy, according to the requirement type (theme, feature, or user story). See Adapt your ALM project for details.
Synchronization of a specific requirement fails if the type of requirement changes. For example, a requirement that is mapped to a theme cannot be subsequently mapped to a user story.
Requirements in the hierarchy defined as types other than theme, feature, or user story may exist, but are ignored during bidirectional synchronization.
When synchronizing requirements defined as features, any ALM Product field that is mapped to an Application field in Agile Manager is reflected in synchronized user stories associated with that feature.
For each requirement type mapping, one endpoint is selected as master for the record synchronization. Which endpoint is the master defines many of the rules for the master and non-master endpoint.
Synchronizer maintains the hierarchical requirements tree structure during synchronization, based on the master endpoint:
|New parent requirements||
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 filter is defined, the parent requirements are synchronized even if they do not match the filter.
If a requirement is moved within the requirements tree of the master endpoint, it is moved accordingly in the other endpoint.
|Alternate root folders||
If you selected an alternate root folder in the Connectivity tab, requirements moved out of the specified folder are handled as deleted requirements.
|Deleted parent requirements||
If a parent requirement is deleted in the master endpoint, and the option to delete corresponding records in the other endpoint is selected, the parent requirement and all child requirements are deleted in the other endpoint.
When a deleted parent requirement is recreated in an endpoint, the child requirements are also recreated.
When a requirement is created in the ALM endpoint during synchronization, it is created with a Checked In status. A comment is added to the requirement's version history specifying that this requirement was created automatically.
When a requirement is updated in the ALM endpoint during synchronization, Synchronizer creates and checks in a new version of the requirement. A comment is added to the requirement's version history specifying that the requirement was modified by the Synchronizer.
When synchronizing a requirement that is checked out by the ALM user defined for the link, the requirement is updated and the new version of the requirement is checked in.
Caution: Requirements that are checked out by an ALM user other than the user defined for the synchronization link are not synchronized.
Group stories are not reflected in the ALM requirements tree. Therefore, Synchronizer does not automatically recognize Agile Manager Group Stories, and does not synchronize any group (parent/child) relationship between stories.
If a requirement in ALM is synchronized with a user story in Agile Manager, and that user story is later broken into a group story (in Agile Manager), Synchronizer considers the user story to have been deleted.
If the link is configured to recreate deleted user stories in Agile Manager based on the corresponding requirements in ALM, the original user story is recreated as a duplicate in Agile Manager.
Tip: Synchronize the group story by creating a user defined field in ALM and mapping it to the Agile Manager Group Story field. The name of the group (parent) story is synchronized to the mapped ALM user defined field.
This synchronization is always unidirectional, from Agile Manager to ALM.
For details about creating user defined fields in ALM for Synchronizer, see Create user defined fields for additional Agile Manager fields.
Tip: For a brand new ALM project, there is no need to migrate requirements to Agile Manager.
Perform a one-time synchronization to migrate ALM requirements into Agile Manager:
Create a link. In the Subtype Mapping > Rules tab, define ALM as the View or update rules and mapped fields (requirements).
Create filters to migrate only the relevant information to Agile Manager.
For example, historical information and closed defects may well not be relevant.
Tip: You may want to first create a small filter to verify that the synchronization works as you expect it to, and enlarge it bit by bit until all your requirements are included in the synchronization.
These filters should also be used for ongoing synchronization.
Once your ALM requirements are created in Agile Manager, assuming you choose to manage your backlog in Agile Manager, modify the link so that Agile Manager is the Master of this link.