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.
For defects or releases: Field Mapping tab
For requirements: Subtype Mapping tab> Select a mapped pair and click Configure > Field Mapping tab
The Field Mapping tab displays requirement type, field type, and permission type for each field available in the endpoints, as well as the mapping direction and other properties for each pair of mapped fields.
Icons indicate whether the field is mandatory for the endpoint, strongly recommended, or optional for you to map.
Mandatory fields must be mapped as a destination of a field in the other endpoint, or configured with a constant value.
Errors occur during integrity checks if records can be created in the endpoint and synchronized to the other endpoint, but mandatory fields are not mapped.
Fields are set as Mandatory if they are required in ALM, but not given a default value in ALM when a record is created.
Recommended fields should be mapped as the destination of a field in the other endpoint, although you are still able to run synchronization tasks on this link without mapping this field.
Warnings occur during integrity checks if records can be created in the endpoint and synchronized to the other endpoint, but recommended fields are not mapped.
Fields are set as Recommended if they are required in ALM and are given a default value in ALM when a record is created.
|Fields are set as Optional if they are not required in ALM, and are not given a default value in ALM when a new record is created.|
Synchronizer indicates whether the field is read-only (R), or has read- and write-permissions (RW). You cannot map read-only fields.
- Bidirectional. (Default) Changes made to data in either endpoint are always updated in the other endpoint. Always define a Dominant side in case of conflicts.
- Unidirectional. Changes made in the destination endpoint may be overridden by changes made in the source endpoint, even if they were made later.
What do you want to do?
Caution: Before mapping endpoint fields, read through the following topics for the data you want to map:
- Guidelines for specific types of fields
- Guidelines for requirements and user stories, themes, and features
- Guidelines for releases and sprints
Incorrect mapping can cause errors in synchronization, or incorrectly synchronized data.
Sort the fields by the data in a particular column by clicking the column header.
Filter the fields to display only fields with a specific requirement level by clicking the icons above the grid.
For example, to show only Mandatory fields, click the Mandatory button.
- To view the properties of a specific field, select the field and click View field properties .
- To view properties for both fields in a mapped pair, select the pair in the Mapped Fields list, and click the Mapping Properties tab on the right.
Note: Each field in one endpoint can be mapped to only one field in the other endpoint.
Different types of fields and mapping directions require various types of property settings. For details, see Edit the properties for a specific pair of mapped fields.
Additionally, see Guidelines for specific types of fields for the specific type of field you want to map.
In each endpoint's grid, select the fields you want to map and click Map Selected Fields at the top of the tab.
To delete a mapping, select the pair and click Delete Field Mapping .
To verify a mapping, select a pair and click Check Field Mapping . Reports include errors that will cause the link to fail, warnings that may prevent the link from running correctly, and other information. For details, see Checks performed on link field mappings.
Select the pair in the Mapped Fields list, and then click the Mapping Properties tab.
Specifically, update the following properties in specific situations:
Relevant for bidirectional mapping. Defines which endpoint overrides the other endpoint if there are changes made to the same record in both endpoints.
By default, ALM (Endpoint 1) is the dominant endpoint.
Agile Manager (Endpoint 2) is set as the dominant endpoint.
Since the last synchronization, a field value was changed in both Agile Manager and ALM, to different values. In Agile Manager, the value was changed to 20, and in ALM, the value was changed to 10.
During the next synchronization, Synchronizer changes the value in ALM to 20, as defined in Agile Manager, the dominant endpoint.
|Synchronize back on create||
Relevant for a single directional mapping. Defines whether Synchronizer sends any new field values created in a destination endpoint (during synchronization) back to the source endpoint.
Tip: Use this option to synchronize custom fields you created to map ALM and Agile Manager IDs. For details, see Prepare ALM and Agile Manager to synchronize ALM and Agile Manager IDs.
A new record was created in ALM. During synchronization, that new record is added to Agile Manager, which generates an Agile Manager ID. Synchronizer now recognizes this new ID field value, and sends it back to ALM, adding it to the source record.
This property helps to ensure that both endpoints contain exactly the same data.
|Require matching field types||
Defines whether the types of fields must match in a pair.
Yes. Mapping fields of different field types is not permitted and the integrity check will fail.
No. Set when you are mapping a String field with a Number or Double field. In this case, integrity checks will fail if this property is set to Yes.
To map the Agile Manager Req ID field, which is a Number field, you might create a user-defined string field in ALM.
When you map these fields, you must set the Require matching field types property to No.
Relevant for User list fields. Defines whether the field values are defined by:
Default. The field is mapped manually, in the Value Mapping tab.
File. The field is mapped using a user list mapping csv file.
Files for mapping user list fields are located in the <Synchronizer installation directory>\dat\Mappings folder.
|Mapping method value||
Relevant for User list fields, when the Mapping method is set to File. Defines the name of the csv file that contains user list mapping.
Files are stored in the <Synchronizer installation directory>\dat\Mappings folder.
Defines a constant value for a field.
For Multi list fields, separate values by semi-colons.
Note: You can also use this procedure to map individual user list field values. However, if you have many users to map, you might want to use a .csv file, as described below.
If your ALM users are defined with email addresses, and those email addresses are identical to those used to log in to Agile Manager, the users are mapped automatically.
In the Mapped Fields list, select the pair of mapped fields for which you want to map specific values, and click the Value Mapping tab on the right.
Click Add Value Mapping or Edit Value Mapping .
In the Add Value Mapping dialog box, select the field values in each endpoint that you want to map, as well as the mapping direction for this field value.
Tip: Endpoint 1 is ALM and Endpoint 2 is Agile Manager.
- To remove a mapping between field values, in the Value Mapping tab, select the mapped pair of values and click Delete Value Mapping .
Note: See Guidelines for mapping user list fields.
In the Field Mapping tab, select and map a pair of User list fields (such as an Assigned to field), and then select the mapped pair in the Mapped Fields list below.
In the Mapping Properties tab on the right, set the Mapping Method property to File.
Click the Value Mapping tab, and then click Add Value Mapping .
In the Value Mapping dialog box, select your mapping file from the Existing mapping files list, and then click Load. Click Refresh if you do not see your file.
Select user values for each endpoint, and use the direction selector and arrow buttons to add pairs to the list of mapped values.
In each endpoint, click Add to add a Default user, and map a user in each endpoint to the Default user in the other endpoint.
Caution: If the Default user is not mapped, synchronization fails for non-mapped user records.
When you map the Default user, the direction must be unidirectional.
Click Save to save changes to the currently selected file or Save As to save the mappings to a new .csv file.
You cannot save the mapping file unless the Status message at the bottom of the dialog box reads OK.
To use this .csv file for mapping field values, click Set as mapping before closing the file.
Select the field to which you want to map a constant value, for new records created in the endpoint.
For example, if you want to define a constant value for a field in ALM for records that were added in Agile Manager and created during synchronization in ALM, select the field in the column listing ALM fields.
Click Add Constant Value above that endpoint's field grid, and enter the value you want to use as a constant.
To add multiple constant values for Multi value list fields, select multiple values from the Value selection list.
To export the currently configured field mappings, click Export. The mappings are exported to an XML file.
To import field mappings, click Import.
Browse to either a previously exported XML file, or a sample file, stored in <ALM Synchronizer Client directory>\samples.
When importing mappings from a sample file, select the file for the type of entity link you are configuring.