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 Prepare for ALM synchronization and Prepare for JIRA synchronization.
Guidelines for mapping specific field values
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, make sure each value is mapped to a value in the other endpoint.
Example of mapping field values: ALM Octane Phase and ALM or JIRA Status.
New field values created during synchronization (Synchronize back on create)
ALM Octane Synchronizer sends any new field values created in a destination endpoint (during synchronization) back to the source endpoint, if they are mapped.
Mapping value list fields
You can synchronize value list fields between ALM or JIRA and ALM Octane. This includes value list fields of type release, team, user, and string (for example, if a defect impacts a number of releases, or a number of teams).
You can also map list fields to a string, for example to save them for reference. For releases, teams, and users the direction of mapping is one direction only, from list -> string. In the case of a single value list of strings, it can be synchronized in both directions.
Automatic field value mapping
If you have identical list values in both ALM or JIRA, and in ALM Octane, they are automatically mapped when you run an integrity check. For example, if you have a Priority list field with the values <Low;Medium;High> in JIRA, and you have the same values defined in ALM Octane, you do not need to map these values to each other. During the integrity check they are automatically mapped, and you only need to map the values that are unique to one of the endpoints. If you do not map a value that is unique on one endpoint, you will receive an error when you run synchronization.
Values are automatically mapped by name in the case of simple lists (strings, numbers), releases, labels and teams. For users, mapping is done according to email address.
Guidelines for mapping attachments
When synchronizing files attached to records, ALM Octane 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, ALM Octane 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 or JIRA, ALM Octane users must have access to the project to open the attachment.
|
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. |
| File encoding |
Supported file encoding when synchronizing attachments: UTF-8, UTF-16LE, or UTF-16BE
|
|
Attachment updates |
ALM Octane 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. |
|
Deleted attachments |
|
Note: ALM System Info attachments (.tsi files) are opened from ALM in a built-in ALM viewer. They are opened from ALM Octane as XML files.
Guidelines for mapping fields with string, float, and numeric values
| If... | Then... |
|---|---|
| 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 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 not 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 |
Synchronizer recognizes date strings of the following formats:
|
Note: Synchronization of multi-value user-defined fields is not supported.
Guidelines for mapping links between entities
Note: It is important to distinguish between Synchronizer endpoint links (such as those between ALM and ALM Octane) and entity links between entities, such as defects
Links between entities are not synchronized.
Guidelines for mapping Release and Cycle fields in defectIf you map ALM Target Cycle or Detected in Cycle fields, you must also map the corresponding release fields.
Additionally:
-
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, \Flight Application\Release_2.
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.
