Review and adapt data for ALM synchronization

Before synchronizing records between 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, 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: In both endpoints, 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.

Back to top

In ALM, prepare requirement types to match ALM Octane's (requirement synchronization)

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 Optional: Specify how to handle requirements whose hierarchy does not match the backlog tree (requirement links).

  • 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

  1. 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.

  2. 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.

Back to top

Check for releases that already exist in both endpoints (Releases synchronization)

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...
  • You have a current ALM release named Release_1.3, as well as a current ALM Octane release named Release_1.3
  • You define 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 ALM Octane release Release_1.3.

 

  • You have:

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

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

  • You define 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.

Back to top

In ALM, create or modify fields

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.

Defining fields as Lookup List fields lets you have empty lists, but still use this field for grouping in ALM.

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.

Back to top

Notes for epics, features, teams, and attachments

Epics and feature names must be unique in both ALM and ALM Octane, and team names must be unique in ALM. If duplicate values are found during synchronization, the related record is not synchronized.

In 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.

Note: Avoid special characters (~!@#$%()^&) in attachment names, as these may cause unexpected behavior during synchronization.

Back to top

Notes about maximum record sizes

ALM Octane Synchronizer supports a maximum record size of 12 MB. This means that synchronizing records larger than 12 MB will cause errors.

If you have records that are larger than 12 MB, move some of the data from the Description, Comment, or any other custom free text field, to a separate file. Then, add the file to the record as an attachment. Attachment sizes are not included in the maximum record size, though they are synchronized between the endpoints.

Back to top

Next steps: