Prepare for ALM synchronization

Before synchronizing records between ValueEdge and ALM Octane and ALM, adapt the data in either endpoint to match the fields supported in the other endpoint, as well as synchronization requirements.

For example, ValueEdge and ALM Octane defects can also be associated with a feature. To synchronize this field, you must create a corresponding user-defined field in ALM.

In ALM Octane, user stories are often arranged in a hierarchy, under features and epics. To synchronize these records and their hierarchy with ALM, you must create a corresponding hierarchy of requirement types.

Optional: Create corresponding ID fields

In both endpoints, we recommend creating user-defined or custom fields to represent the record ID in the other endpoint. Define these fields as Number or Numeric fields.

In ALM, create a field named ALM Octane ID.
In ALM Octane, create a field named ALM or QC ID.

Later, map these corresponding fields in the link's Field Mapping tab. For details, see Edit field mapping.

Create a subset of requirements or releases

By default, ALM Octane Synchronizer synchronizes:

the entire ALM Requirements root folder, including sub-folders.
all current releases (with an end date that has not yet passed) in the ALM Releases root folder, including sub-folders.

To synchronize only a subset of the requirements or releases in your ALM project, you can specify an alternate root folder in the synchronization link.

Note: If you use both favorites and alternate root folders, Synchronizer considers the alternate root folder before the favorites.

In the ALM project's tree, create a sub-folder that contains only the requirements or releases that you want to synchronize. This sub-folder can also include additional sub-folders.

For details on defining the alternate root folder in your synchronization link, see Optional (ALM): Define an alternate root folder.

Prepare requirement types in ALM

Decide on ALM requirement types that represent ALM Octane epics, features, and user stories, and arrange them in a hierarchy that matches the one in ALM Octane.

Rules for matching the ALM and ALM Octane hierarchies

You can map one or more ALM requirement types to each of the ALM Octane types: user story, feature.
You can map only one ALM requirement type to ALM Octane epics.
If you do not map a specific ALM requirement type, requirements of that type are not synchronized.
ALM Octane quality stories are not synchronized.
If your ALM hierarchy does not match the ALM Octane hierarchy, Synchronizer can synchronize requirements directly to the root of ALM Octane's backlog tree. This is relevant only for requirements mapped to epics or user stories. For details, see Mismatches between requirement hierarchy and backlog tree.
Synchronization may fail if:
- You do not map all requirement types, including Epic, Feature, and User Story.
- Synchronized requirements are not located in the correct location in the ALM hierarchy. For example, if a feature requirement is located under a user story requirement in the ALM requirement tree.
- You change a requirement's type after it was synchronized.

To create the requirement hierarchy in ALM:

If needed, create new user-defined requirement types in ALM customization.

Note: You can include requirements of type Folder in your hierarchy. These are considered requirement sub-folders. Folder type requirements are not synchronized, but the requirements they contain are synchronized.

Here is a suggestion for a simple hierarchy to use:
- Use the ALM's out-of-the-box Business requirement type to represent epics.
- Use ALM's out-of-the-box Functional requirement type to represent features.
- Create a new User Story requirement type in ALM to represent user stories.
Create or modify the requirement tree with a maximum of three levels (representing epics, features, and user stories).
- Requirements synchronized with epics must be at the top of the hierarchy.
- Requirements synchronized with features must be under epics.
- Requirements synchronized with user stories can be under features, or at the top level, but not under epics.
ALM Octane Synchronizer retains the hierarchy during synchronization.

The three-level hierarchy can be stored in any requirement folder or sub-folder. In ALM Octane, the synchronized tree is stored under the Backlog root.

Example of a requirement hierarchy

Requirement type mapping:

ALM Group requirements >> ALM Octane epics.
ALM Functional requirements >> ALM Octane features.
ALM Performance and Testing requirements >> ALM Octane user stories.

After synchronizing:

The requirements ALM Group 001 (epic) and ALM Group 002 (epic) are created on ALM Octane as two sibling epics under the root of the ALM Octane backlog tree.
The requirement ALM Functional 002 (feature) is created as a feature under the epic ALM Group 002 (epic).
The requirement ALM Testing 002 (userstory) is created as a user story under the feature ALM Functional 002 (feature).
The requirement ALM Performance 002 (userstory 2nd) is created as a user story under the root of the ALM Octane backlog tree.

Check releases in both endpoints

Check whether you have releases or sprints/cycles with the same names defined in both ALM and ALM Octane. If you do, we recommend that in the release synchronization link, you select the Map pairs of new releases and sprints/cycles with identical names option.

The data from the dominant endpoint is then used for all release entities, overriding any data in the other endpoint.

Why select this option?

If identically named releases or sprints are found and are not mapped, these releases or sprints are not synchronized at all and a "duplicate entities" error is generated in the Run Report.

This is because ALM Octane Synchronizer tries to handle the release as a new record, creating it in the destination endpoint.

The synchronization fails because the destination endpoint already has a release or sprint/cycle with the same name.

If you later change the name of one of the releases or sprints, so that the duplication does not occur, the ALM Octane Synchronizer re-creates it in the destination endpoint.

Mapping option is limited to current releases

When mapping, ALM Octane Synchronizer checks only the releases that are included in the synchronized time frame. Releases or sprints/cycles with identical names are not mapped if they are in a past release (or a release whose end date is older than the one you specified for synchronization).

For details on synchronizing past releases, see Synchronize past releases.

For example:

If... Then...

If...	Then...
You have a current ALM release named `Release_1.3`, as well as a current ValueEdge and ALM Octane release named `Release_1.3` You define ValueEdge and ALM Octane as the dominant endpoint for the release link fields (in the Field Mapping tab) You select the Map pairs of new releases or sprints found with identical names option in the Rules tab	The two releases are mapped. All data in the ALM release `Release_1.3` is overwritten by the data in the ValueEdge and ALM Octane release `Release_1.3`.
You have: An ALM release named `Release_1.3`, whose end date is July 20, 2017. An ValueEdge and ALM Octane release named `Release_1.3`. whose end date is July 30, 2017. You define ValueEdge and ALM Octane as the dominant endpoint for the release link fields (in the Field Mapping tab) You select Synchronize past releases. End date can be this date or later: `July 25, 2017`. You select the Map pairs of new releases or sprints found with identical names option in the Rules tab.	The ALM release is not relevant for mapping, because it is too far in the past. However, synchronizing `Release_1.3` to ALM fails because it tries to create a release on ALM with a name that already exists.

You have a current ALM release named Release_1.3, as well as a current ValueEdge and ALM Octane release named Release_1.3
You define ValueEdge and ALM Octane as the dominant endpoint for the release link fields (in the Field Mapping tab)
You select the Map pairs of new releases or sprints found with identical names option in the Rules tab

The two releases are mapped.
All data in the ALM release Release_1.3 is overwritten by the data in the ValueEdge and ALM Octane release Release_1.3.

You have:

An ALM release named Release_1.3, whose end date is July 20, 2017.

An ValueEdge and ALM Octane release named Release_1.3. whose end date is July 30, 2017.
You define ValueEdge and ALM Octane as the dominant endpoint for the release link fields (in the Field Mapping tab)
You select Synchronize past releases. End date can be this date or later: July 25, 2017.
You select the Map pairs of new releases or sprints found with identical names option in the Rules tab.

The ALM release is not relevant for mapping, because it is too far in the past.

However, synchronizing Release_1.3 to ALM fails because it tries to create a release on ALM with a name that already exists.

Create or modify fields in ALM

In ALM, modify the fields listed in the following table. If a field does not already exist in ALM, create a user-defined field to correspond to this data in ALM Octane. For details about mapping fields after setting up your link, see Edit field mapping.

Field name	Description
Application module	Define as a Lookup List field. Configure ALM to Allow Multiple Values and not to verify this value. Tip: Alternatively, when editing your link, map the ALM Octane Application module field to the ALM Product field.
Owner	Define as a User List field.
Blocked	Define as a String field.
Feature	Define as a Lookup List field. Configure ALM not to verify this value.
Rank	Define as a Number field.
Story points	Define as a Number field.
Phase	Define as a Lookup List field. Configure ALM not to verify this value.
Team	Define as a Lookup List field. Configure ALM not to verify this value.
Epic	Define as a Lookup List field. Configure ALM not to verify this value. Note: Required for requirements being synchronized as features.

Tip: You may want to create an additional user-defined field to distinguish between entities created directly in ALM and those synchronized from ALM Octane.

To do so, create a field in ALM named Creation Method. Later, when you are mapping fields, assign a constant value of created by ALM Octane Synchronizer. For details about assigning constant values, see Edit field mapping.

ALM version control

If you synchronize with an ALM project that uses version control, ALM Octane Synchronizer conforms to the versioning rules. Changes made by the synchronization process are checked in with a comment: Modified by Synchronizer.

During synchronization, ALM Octane connects to ALM using the credentials of an ALM user that you specify.

When synchronizing an entity that is checked out by that user, the entity is updated and checked in.
When synchronizing an entity that is checked out by a different user, the ALM entity is not modified.
- If the synchronization is governed by the ALM Octane side, a synchronization error occurs due to the locked entity in ALM.
- If the synchronization is governed by the ALM side, the ALM Octane entity is updated based on the last checked-in version on ALM.

Notes and limitations

This section lists known issues and limitations relating to the Synchronizer.

Epics and feature names must be unique in both ALM and ALM Octane, and team names must be unique in ALM. Requirement names must be unique in ALM if they are under the same parent. If duplicate values are found during synchronization, the related record is not synchronized.
In ValueEdge and ALM Octane, records assigned to a specific feature must also have an epic defined. If you synchronize features, you must also synchronize their epics. Therefore, if you map epic and feature fields, we recommend making them required fields in ALM to avoid synchronization errors.
The Synchronizer does not support synchronization of MEMO fields containing image tags. If you want to be able to synchronize such entities, the shared space parameter MEMO_FIELD_IMAGE_VALIDATION must be set to false.
Avoid special characters (~!@#$%()^&) in attachment names, as these may cause unexpected behavior during synchronization.
Line Height is ignored when synchronizing from ALM Octane to ALM. If you update description in ALM and run synchronization again, the line height is not kept in ALM Octane as well.