Guidelines for specific types of fields

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.

Read through the following sections for guidelines on Synchronizer treats specific types of fields, and tips for mapping them.

Note: Record history data is not synchronized.

For task details, see Map endpoint fields.

Agile Manager and ALM maintain separate lists of user fields, such as the Assigned To field.

If you have users that exist in one endpoint but not in the other, you must map them to a Default user in the opposite endpoint. This may happen, for example, if a user once existed in an endpoint's user list, and is therefore listed as a value, but has since been deleted from the other endpoint's user list.

Note: When you map the Default user, the direction must be unidirectional. Otherwise, using the Default user can potentially cause data loss in the same way that mapping any specific value in one endpoint to multiple values in the other endpoint can.

Additionally, the default users works for ALM users who are not defined with any email address only. If an ALM user is indeed defined with an email address, you must map that user manually, in bulk, or ensure that the user can be mapped automatically.

The following table describes user mapping methods in detail:

Automatic mapping

ALM users defined with an email address that is identical to the one used to log in to Agile Manager are automatically mapped for all user list fields.

If a user has multiple email addresses defined in ALM, only the first email address is synchronized with Agile Manager.
Manual mapping

Map ALM and Agile Manager users manually if the email addresses are not identical, or if the ALM user is not defined with an email address.

Do this using the same process you use to map other specific field values in the Value Mapping tab. For details, see Map specific field values.
Bulk mapping

Map ALM and Agile Manager users in bulk if you have many users whose email addresses do not match in ALM and Agile Manager, and therefore are not mapped automatically.

Use a .csv file, which you can create and edit directly in the Synchronizer client or any text editor.

For details, see Map user list fields using a .csv file.

If you map attachment fields for a specific link, when a file is attached to the record in the source endpoint, Synchronizer generates a URL for that file, and passes it to the corresponding record in the destination endpoint. If a URL is attached to the record in the source endpoint, Synchronizer simply passes it to the destination.

From then on:

Updated attachments

Synchronizer updates an attachment if both of the following have changed:

  • The record to which the file is attached
  • The attachment name, size, or last modified property

The attachment description is synchronized only during the initial attachment synchronization, and is never updated.
Deleted attachments in the source endpoint

If an attachment is deleted from the record in the source endpoint, Synchronizer also deletes it from the corresponding record in the destination endpoint.
Deleted attachments in the destination endpoint

If an attachment is deleted from a destination endpoint, and changes are later made to the attachment in the source endpoint, the attachment is recreated in the destination endpoint.

You can modify this behavior in the server.properties file.

Notes for new attachments

Separate attachments in opposite endpoints with the identical file names You cannot synchronize attachments for the same entity that have identical file names. If this happens, the task report may display a failed status, depending on the configuration set in the server.properties file.
File encoding URL attachments created in ALM use the file encoding configured in the server.properties file. If Synchronizer cannot determine the encoding, it cannot synchronize the URL attachments to Agile Manager.

Opening attachments

Permissions Users must have appropriate permissions in both endpoints to open the synchronized attachment.
ALM System Info attachments 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.

  • 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, map them to numeric fields in Agile Manager to avoid inaccuracies.

    By default, Synchronizer recognizes float fields as strings.

    This is relevant for projects stored in ALM versions 11.5x only.

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.

  • Synchronization of entity links is not supported when connecting to ALM using external authentication. For details, see Connect to ALM using external authentication.

  • Synchronization of entity links is supported for ALM versions 11.50 and later.

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 mapping entity links between defects and requirements:

  • You must be synchronizing both defects and requirements by the same Synchronizer server.

  • The link fields are mapped using the same direction as is used by the link synchronizing defects on that Synchronizer server.

  • When synchronizing requirements, only entity links between two user stories are synchronized.
  • When synchronizing defects, all entity links are synchronized, including links between two defects and links between a defect and a user story.

When synchronizing deleted records with links to other entities:

Synchronization of entity links when one record has been deleted conforms to the same rules for deletion as the records themselves.

Links to other records are affected as follows, depending on the rule selected:

Rule Action
Do nothing The links between the records are not deleted in the other endpoint.
Delete its corresponding record in the other endpoint The links to other records are deleted together with the deleted record itself, in the other endpoint.
Recreate based on its corresponding record in the other endpoint The links to other records are recreated together with the record itself, in the original endpoint.

For details, see Configure link properties.

When synchronizing from Agile Manager to ALM, map the ALM Product field to the Agile Manager Application field.

If a new Application is added to a user story or defect in Agile Manager, the new Product value is not automatically created in ALM. To synchronize these new Product and Application values, add the new Product value in ALM.

  • 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, that defect or requirement is not synchronized.

    Caution: 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 map the Feature field to be synchronized from ALM to Agile Manager (or in a bidirectional synchronization), you must also map the Theme field.

    Synchronizer generates an error if it finds a record in ALM that is assigned to a Feature, but no Theme.

Tip: If you are mapping Feature and Theme fields, we recommend making them required fields in ALM to avoid synchronization errors.

The following ALM release and cycle fields are available for mapping in defect and requirement links:

  • Requirements: Target Release, Target Cycle
  • Defects: Target Release, Target Cycle, Detected in Release, Detected in Cycle

Note: For guidelines about configuring links to synchronize releases and sprints, see Guidelines for releases and sprints.

To map a cycle field, you must also map the corresponding release field. For example, if you map the Target Cycle field, you must also map the Target Release field.

Additional notes:

Release and cycle or sprint names Must be identical, with the same name and capitalization, in both endpoints.
Release names Must be unique in both endpoints. If they are not, and you map release fields, an error is written to the task report and the relevant records are not synchronized.
Target release for 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, \Flight Application\Release_2.

You do not need to include the root Releases folder in the path.

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 not team defined for the record, no team value is assigned during synchronization.

Synchronizer enables you to map specific field values in one endpoint to specific values for the corresponding field in the other endpoint.

This is supported only for the following types of fields: String, Single value list, Multi value list, and User list

For task details, see Map specific field values.

Caution: 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.

If a field has a different number of values in the different endpoints and you map the field itself bidirectionally, the extra values on one of the endpoints will be overwritten.

Example:  

  • You have an ALM Priority field, with values of Low, Medium, High, and Critical.

    You map the Priority field to an Agile Manager Importance field, with values of 1, 2, 3, and 4.

    In this case, map Low to 1, Medium to 2, and so on. When the ALM Priority value changes from Medium to High, Synchronizer changes the Agile Manager Importance value from 2 to 3.

  • If however, suppose the Agile Manager Importance field had only three values, of 1, 2, and 3.

    If you map both Priority fields Medium and High to the Importance value 2, Synchronizer changes both Medium and High values to 2 during synchronization.

    When synchronizing the same record back to ALM, the Priority field may be given a value of High, when it was actually originally Medium.

Assign constant values to fields instead of mapping them to a corresponding field in the other endpoint, such as when there is no corresponding field. The constant value is assigned to the field when Synchronizer creates new entities, and is not updated in subsequent synchronizations. Multi value list fields support multiple constant values.

For task details, see Map constant values.

Example: You may want to do this if:

  • You have a required field in ALM, but no corresponding field in Agile Manager. Assign a constant value so the required field is considered to be mapped, and integrity links can pass.

  • You want to distinguish between defects created directly in ALM and those synchronized from Agile Manager. Create a defects field in ALM named Creation Method, and assign a constant value of created by Synchronizer.