OSLC Connect for Jira Cloud

1. Overview

When Jira DC is migrated to Jira Cloud using the Atlassian Migration Assistant, the IBM ELM (Engineering Lifecycle Management) server retains project-area associations that still point to the old DC instance. These associations define which OSLC link types can be created between ELM work items and Jira issues. After the migration, those associations are stale and must be replaced with broker-backed equivalents that point to the Cloud-side OSLC Connect broker.

This tool discovers those stale associations on the ELM server, resolves the corresponding Cloud project IDs via the Atlassian ID mapping service, and replaces each DC association with a new broker-backed association. For GCM (Global Configuration Management) applications, the tool also migrates the version references inside global configurations. Additionally, the tool discovers OSLC links on ELM resources that point to Jira DC issues and updates them to their Cloud equivalents.

Supported ELM applications

The tool supports the following ELM application: EWM (CCM), DNG (RM), ETM (QM) and GCM (GC). Instances are configured individually in elm.properties using a user-chosen instance ID. This allows multiple instances of the same application type (e.g. rm1, rm2) and arbitrary context paths.

Each configured instance produces one output file per project area, named elm$<elmInstanceId>$<projectAreaName>$<projectAreaId>$migration.xlsx. For example, an instance named ccm with a project area called “My Project Area” produces elm$ccm$My_Project_Area$_P4kL8DjdEfGzULwSWQuQaA$migration.xlsx. The project area name is sanitized for safe file-system usage (spaces become underscores, special characters are stripped).

Archived project areas are excluded from the migration.

GCM (Global Configuration Management) applications

When an ELM application is a GCM server (detected automatically via its OSLC publisher product abbreviation), the tool performs additional processing. In addition to the standard project_associations sheet, each project-area file includes a global_configurations sheet that lists the configuration-to-version associations found on the GCM server. During update-elm, those associations are replaced on the ELM GCM server via one PUT request per global configuration.

The following types of GCM global configurations are in scope for the migration and are all processed the same way, as long as permissions are assigned correctly (see Required permissions):

• Streams
• Baselines
• Baseline staging streams
• Personal streams

Archived configurations of any type are excluded from indexing and will not be processed.

OSLC link types

The following OSLC link types are indexed and migrated:

2. How It Works

The process follows a fixed sequence of steps. index-elm and update-elm are the two commands in this package.

3. Prerequisites

Software & environment

ELM OAuth 1.0a consumer registration

Required permissions

The functional user associated with the ELM OAuth consumer must have the following repository permissions:

• JazzUsers
• JazzProjectAdmins

Additionally, the user must be assigned at least one of the following licenses (assigned by the server administrator):

This is sufficient for both the indexing and updating phases to run on all project areas.

Additional requirements for updating GCM global configurations

Indexing GCM global configurations does not require any additional permissions. However, to update GCM global configurations containing release links, the functional user must also:

1. Be a member of each project area that contains GCM global configurations with release links to migrate (these project areas are listed in the indexing output files).
2. Have the Project Area Access Control scope set to at least: Members of the project area hierarchy.
3. Hold at least one role with the following permissions:
   • Baselines > Add or remove links > Add or remove Release Links
   • Baseline staging streams > Add or remove links > Add or remove Release Links
   • Other user’s personal streams > Add or remove links > Add or Remove References Links
   • Streams > Add or remove links > Add or remove References Links

Jira DC: Basic authentication must be enabled

Network connectivity

The machine running this tool must be able to reach all of the following:

• ELM server (all application instances configured in elm.properties)
• Jira DC REST API (for ID mapping service, typically port 8080 or 443)
• Jira Cloud tenant (*.atlassian.net and/or api.atlassian.com)
• OSLC Connect broker

4. Configuration Files

Three properties files control how the tool connects to each system. Template files for all three are included in this package. Edit them with a plain text editor before running anything.

elm.timeoutMs=30000

elm.app.ccm.url=https://elm-server.example.com/ccm
elm.app.ccm.consumerKey=...
elm.app.ccm.consumerSecret=...

elm.app.rm1.url=https://elm-server.example.com/rm1
elm.app.rm1.consumerKey=...
elm.app.rm1.consumerSecret=...

elm.app.rm2.url=https://elm-server.example.com/rm2
elm.app.rm2.consumerKey=...
elm.app.rm2.consumerSecret=...

0 Meet the Prerequisites

1 Prepare Your Configuration Files

1. Open config/elm.properties and configure each ELM application instance with its full URL and OAuth 1.0a consumer credentials.
2. Open config/rest.properties and fill in your Jira DC base URL and credentials. The base URL is used to identify Jira DC resources among ELM resources, and to fetch the ID mapping service (unless --idmappings provides a CSV file).
3. Open config/cloud.properties and fill in your Jira Cloud tenant URL, credentials, and broker URL.

2 Run the Indexer (index-elm)

Open a terminal in the folder where this package is installed and run one of the commands below. The Indexer will fetch the Atlassian ID mapping table first, then connect to the ELM server to discover project-area associations, and finally write one Excel file per project area into the output folder.

chmod +x bin/index-elm.sh bin/update-elm.sh

Index all configured ELM instances — Windows

bin\index-elm.bat --elm config\elm.properties --rest config\rest.properties --cloud config\cloud.properties --dir output\

Index all configured ELM instances — Linux

bin/index-elm.sh --elm config/elm.properties --rest config/rest.properties --cloud config/cloud.properties --dir output/

Index using a local CSV mapping file — Windows

bin\index-elm.bat --elm config\elm.properties --rest config\rest.properties --idmappings id-mappings_20260612_143052.csv --dir output\

Index using a local CSV mapping file — Linux

bin/index-elm.sh --elm config/elm.properties --rest config/rest.properties --idmappings id-mappings_20260612_143052.csv --dir output/

Index specific instances only

bin\index-elm.bat --elm config\elm.properties --rest config\rest.properties --cloud config\cloud.properties --applications ccm,rm1 --dir output\

All available options

Output

After the Indexer finishes, you will find one Excel file per project area in the output folder. For example, with instances ccm and rm1:

output/
  elm$ccm$My_Project_Area$_P4kL8DjdEfGzULwSWQuQaA$migration.xlsx
  elm$ccm$Another_PA$_R3nT5VkdEfJzWNxUYSuTcC$migration.xlsx
  elm$rm1$My_Project_Area$_P4kL8DjdEfGzULwSWQuQaA$migration.xlsx
  elm$rm1$Other_PA$_K7xM2QjdEfHzULwSWQuRbB$migration.xlsx

Each file contains a project_associations worksheet. For GCM applications, a global_configurations worksheet is also created, listing the configuration-to-version associations discovered on the GCM server. For applications with supported OSLC link types, a links worksheet is also created, listing the OSLC links pointing to Jira DC issues. See the Appendix for the full column reference.

Files are only created when at least one migratable association is found for the project area. Project areas with no associations produce no output file.

Logging

The scripts are pre-configured to load config/logback.xml. By default that file sends log output to two destinations simultaneously:

• Console – information and errors are printed to the terminal in real time.
• Rolling file – a persistent log is written to ~/oslc-connect-jira-cloud-migration/logs/migration.log and rotated daily. Up to 10 compressed daily archives are kept (total cap 2 GB).

3 Review the Excel Files

Open the generated Excel files and review the results before running the Updater. Each row represents one project-area association and includes a status column that tells you the outcome of the indexing step.

Common status values after indexing

→ Full list of all status values in the Appendix

Optional adjustments you can make

You can manually edit the status column of any row to control how the Updater handles it:

• Set to OMIT to intentionally skip a record (e.g. an association that should not be migrated).
• Set to REPROCESS to force the Updater to re-post a record even if it was previously completed successfully.

4 Run the Updater (update-elm)

The Updater reads the Excel files produced by the Indexer and, for each project area, adds the new broker associations and removes the old DC associations on the ELM server in a single request. The outcome of each row is written back into the same files, so you always have a full audit trail.

chmod +x bin/index-elm.sh bin/update-elm.sh

Run the Updater (all files) — Windows

bin\update-elm.bat --elm config\elm.properties --cloud config\cloud.properties --dir output\ --all-projects

Run the Updater (all files) — Linux

bin/update-elm.sh --elm config/elm.properties --cloud config/cloud.properties --dir output/ --all-projects

Verify without posting (dry run)

Use --verify to parse and validate all input files without making any ELM server calls. Useful to check the state of the working directory before committing updates.

bin\update-elm.bat --elm config\elm.properties --cloud config\cloud.properties --dir output\ --all-projects --verify

Update specific project-area files only

bin\update-elm.bat --elm config\elm.properties --cloud config\cloud.properties --dir output\ --projects elm$ccm$My_Project_Area$_P4kL8DjdEfGzULwSWQuQaA$migration.xlsx,elm$rm1$Other_PA$_K7xM2QjdEfHzULwSWQuRbB$migration.xlsx

All available options

What the Updater does per project area

Updatable rows are grouped by project area. For each group, the Updater performs a two-phase cycle on the ELM server:

1. GET stateId — fetches the current project area state ID. The ELM API uses the state ID as an optimistic-locking token: every write request must include it.
2. POST add + remove — adds the new broker-backed associations and removes the old DC associations (identified by old_id) in a single request, using broker URLs built from new_id, dc_sp_domain, and broker.baseUrl.

If the POST fails, all rows in the group are marked as FAILED_UPDATE.

What the Updater does for GCM global configurations

When a global_configurations sheet is present (GCM applications), the Updater processes each global configuration through a GET–replace–PUT cycle:

1. GET configuration — fetches the current XML representation of the global configuration and its ETag header for optimistic concurrency control.
2. Replace releases — in the fetched XML, replaces each DC version URL with the corresponding Cloud release URL. If the Cloud URL is already present alongside the DC URL, the DC URL is simply removed.
3. Skip or PUT — if no DC URL was found (the configuration is already up to date), the PUT is skipped entirely and the rows are marked as UPDATED. Otherwise, a PUT is sent with the modified XML body and an If-Match header carrying the ETag from the GET response.

All releases belonging to the same configuration are grouped and sent together in a single request. Authentication uses OAuth 1.0a, same as for project-area association updates.

What the Updater does for OSLC links

When a links sheet is present, the Updater processes each link through a GET–replace–PUT cycle on the ELM server:

1. GET resource — fetches the current XML representation of the ELM resource and its ETag header.
2. Replace links — in the fetched XML, replaces each DC link with the corresponding Cloud link built from new_id and broker.baseUrl. If the Cloud link is already present alongside the DC link, the DC link is simply removed.
3. Skip or PUT — if no DC link was found (the resource is already up to date), the PUT is skipped entirely and the rows are marked as UPDATED. Otherwise, a PUT is sent with the modified XML body and an If-Match header carrying the ETag from the GET response.

Links targeting the same ELM resource are grouped and sent in a single request. Authentication uses OAuth 1.0a.

5 Validate

After the Updater finishes, verify that the migration was successful:

• Review the Excel files: all rows should show UPDATED. Any rows still showing FAILED_UPDATE indicate associations that could not be migrated — check the status_detail column for the error and consider re-running the Updater after resolving it.
• Open the ELM application administration pages and navigate to each project area's Associations section. Confirm that the old DC associations have been replaced with broker-backed equivalents pointing to the Cloud-side OSLC Connect broker.
• Verify that the expected OSLC link types (e.g. “Implements Requirement”) are still available when creating links from ELM work items to Jira issues.

Appendix

GET <dcBaseUrl>/rest/migration/latest/report/id-mappings
    ?cloudSiteUrl=<cloudBaseUrl>&invalidateCache=false

entityType,serverId,cloudId
jira/classic:project,10100,10198
...

Known Limitations

OSLC links to unmigrated issues are not detected

Unlike project associations, which are validated against the Atlassian ID mapping payload and marked FAILED_INDEX when the DC project has not been migrated, OSLC links are not validated against any mapping. Every link targeting the Jira DC base URL receives INDEXED status regardless of whether the target issue actually exists in Jira Cloud.

The Atlassian ID mapping payload cannot be used for this validation because Jira DC OSLC resource URLs contain the issue key (e.g. ALPHA-1), not the numeric issue ID. The mapping payload only holds numeric ID pairs (serverId,cloudId), and resolving a key to its numeric ID would require querying the Jira DC instance, which may already be decommissioned by the time the migration tool runs.

If the target issue was not part of the Jira Cloud migration scope (e.g. its project was not selected for migration), update-elm will overwrite the original DC link in the ELM resource with a Cloud broker URL that does not resolve. The original working DC link is lost.

OSLC links with historical issue keys may resolve to unintended issues

The indexer extracts the Jira issue key from the DC OSLC resource URL stored in the ELM resource (e.g. ALPHA-1 from .../cm/issue/ALPHA-1) and uses it verbatim in the Cloud broker URL (e.g. /cm/change-request/ALPHA-1). No DC-to-Cloud issue key resolution is performed, for the same reason described above: issue keys cannot be resolved to numeric IDs without the Jira DC instance.

The Cloud OSLC broker resolves issue keys by calling the Jira Cloud REST API (/rest/api/3/issue/{issueIdOrKey}), which handles historical keys transparently. In most cases this works correctly.

However, if a pre-existing Cloud issue has the same key as the one stored in the ELM resource, the Cloud API returns the pre-existing issue instead of the migrated one. This can happen when:

• An issue was moved between projects in Jira DC (e.g. ALPHA-5 → BETA-20). The ELM resource still stores the old key ALPHA-5. If Jira Cloud already has an active issue ALPHA-5 from a different project, the migrated link silently points to the wrong issue.
• A Jira DC project was renamed before migration to resolve a pre-flight key conflict with an existing Cloud project. The issue keys changed in DC but the ELM resources still store the old keys, which now belong to the pre-existing Cloud project.

In both cases, Jira’s historical key conflict resolution rules (see Migration of Jira’s historical keys for issues and projects) cause the Cloud active key to take priority over the DC historical key. The link resolves without error but points to the wrong issue.

Troubleshooting

Indexing (index-elm)

Failed to index resource: no new_id found

Failed to index resource "<configTitle> <configUri> <dcVersionUrl>": no new_id found on mapping service response

This error means the ID mapping file does not contain an entry for the Jira DC version referenced by the global configuration’s release link. The ID mapping file is either fetched automatically from the Jira DC instance (using rest.properties) or provided manually via --idmappings. Verify that the corresponding Jira DC version has been migrated to a Cloud release and that the mapping file is up to date.

Updating (update-elm)

403 Forbidden when updating GCM global configurations

If update-elm writes 403 Forbidden errors when processing GCM global configurations, the functional user likely does not meet the permission requirements for GCM updates. See Additional requirements for updating GCM global configurations for the full checklist.