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.
Once a record in one endpoint is mapped to a record in the other endpoint, it is always synchronized if there is new data, regardless of whether the record still matches the link's filter.
Therefore, before you start synchronizing, it is highly recommended that you read the following guidelines for specific types of synchronizations.
For further recommendations before synchronizing, see Adapt the data in your endpoints.
Mapping field values when the number of values differ in each endpoint
If you have a different number of values for the field in each endpoint, select unidirectional mapping for the extra values, as only one value can be synchronized back to the original endpoint.
When we synchronize the field value in the mapped direction, the mapped value is used in the destination endpoint. When synchronizing in the other direction, the value is not mapped to a different value and is either copied as is, or according to a different mapping rule.
New field values created during synchronization (Synchronize back on create)
NextGen Synchronizer always sends any new field values created in a destination endpoint (during synchronization) back to the source endpoint. This is not configurable.
When synchronizing files attached to records, Synchronizer generates a URL for the file, and passes that URL to the destination record. Users in the destination endpoint access the file via the URL, which essentially remains in the source endpoint.
If a URL attachment is added to the record in the source endpoint, Synchronizer simply passes the attached URL to the destination.
For this reason, if you map attachment fields, users must have appropriate permissions in both endpoints to open the synchronized attachment. For example, if a file was originally attached to a record in ALM, Agile Manager users must have access to the ALM project in order to open the attachment.
Caution: If a description in ALM includes an image, the image is synchronized as an attachment, but not displayed in the description in Agile Manager.
In Agile Manager, do not modify the part of the description that contains the image in ALM. Otherwise, the next synchronization could accidentally remove the image from the description displayed in ALM.
Attachment file names
Attachments to the same record must have unique names. Attaching a file or URL to a record in opposite endpoints, with the same file name, will cause errors.
Supported file encoding when synchronizing attachments: UTF-8, UTF-16LE, or UTF-16BE
Synchronizer updates an attachment only if both of the following have changed:
The attachment description is synchronized only during the initial attachment synchronization, and is never updated.
- ALM System Info attachments (.tsi files) are opened from ALM in a built-in ALM viewer. They are opened from Agile Manager as XML files.
- In browsers other than Internet Explorer: To open URL's that link to ALM, copy the link and open it in Internet Explorer.
|If you map a string field that has a maximum length in the destination endpoint, and a synchronized value exceeds this maximum||The string value will be truncated as necessary in the source endpoint during synchronization.|
|If you have user defined float fields in ALM||
You must map them to numeric fields in Agile Manager to avoid inaccuracies.
Note: By default, Synchronizer recognizes float fields as strings. This is relevant for projects stored in ALM version 11.52 only.
|If you map a string field in the source endpoint with a numeric field in the destination endpoint||For the synchronization to succeed, the string field value must be an integer.|
|If you map a numeric or date field in the source endpoint with a list field in the destination endpoint||
For the synchronization to succeed, the numeric or date field value must be one of the values in the list.
Note: In ALM, a list field can be defined no to verify values. In this case, a numeric or date field mapped to the list can contain values that are not in the list.
|If you map a date field with a string field||For the synchronization to succeed, the date format must be yyyy-mm-dd (for example:
Note: It is important to distinguish between Synchronizer endpoint links (such as those between ALM and Agile Manager) and entity links between entities, such as defects and requirements.
Map links between entities, such as links between defects and requirements, the same way you map other fields.
Once you've mapped link fields, entity links between two synchronized entities are synchronized together with the rest of the record. However, if one of the linked entities is not synchronized, the link between them is not synchronized either.
When synchronizing entity links between defects and requirements:
When running a requirement synchronization, only entity links between two user stories are synchronized.
When running a defect synchronization, links between two defects and links between a defect and a user story are all synchronized.
Entity links to/from features or themes are not synchronized.
Only direct links between entities are synchronized.
If a requirement is linked to a test that is linked to a defect, this indirect link between the requirement and the defect is not synchronized.
When synchronizing deleted records with links to other entities:
Synchronization of entity links when one record has been deleted conforms to the same rules as the records themselves. This ensures that no links to non-existent entities remain, and that links are retained or recreated if their records are retained or recreated.
When synchronizing deleted entity links:
Deleting an entity link is an update to the related entity. Therefore, when entity links are deleted, they are handled according to the update rules in the synchronization link, and not the deletion rules.
For example, if the link is set to synchronize all updates between two endpoints, then when entity links are deleted at one endpoint, they are always deleted in the other endpoint during synchronization, regardless of the deletion rules defined in the synchronization link.
When entity links are deleted after exporting a synchronization link from ALM Synchronizer and before importing the link to NextGen Synchronizer, the entity links are recreated when the synchronization runs.
If you map ALM Target Cycle or Detected in Cycle fields, you must also map the corresponding release fields.
Release and cycle or sprint names must be identical in both endpoints. These names are case-sensitive.
Release names must be unique in both endpoints.
Requirements must have a single target release in ALM. Synchronizing requirements from ALM with multiple target releases will fail.
Tip: If you cannot modify these release names but you want to map these fields:
Map specific field values to define the full path of the release. For example, you can map each value of the Target Release field to a value in a corresponding field in the other endpoint.
Define the full path of the ALM release in the format
\<Release_Folder_Name>\<Release_Name>. For example,
You do not need to include the root Releases folder in the path.
For details about mapping specific field values, see View other field properties.
Agile Manager supports both workspace teams, which are available for all releases in a workspace, as well as feature teams, which are available for a specific release only. Although it is not recommended to have a workspace team and feature team with the same name in the same release to prevent confusion and errors, separate teams of different types with the same name are supported.
Such teams are synchronized as follows:
|Agile Manager > ALM||A workspace team or a feature team defined for a record are synchronized to the same ALM team value.|
|ALM > Agile Manager||
Synchronizer first checks for a release team with the name in the record's defined release. If a feature team is found with the configured name, the record is synchronized with the feature team.
If there is no release defined for the record, or if there is no feature team found in the defined release with the configured name, Synchronizer searches for a workspace team with that name. If the workspace team is found, the record is synchronized with that team value.
If no team is found with the configured name, an error occurs. If there is no team defined for the record, no team value is assigned during synchronization.