OSLC Connect for Jira Cloud

1. Overview

The Atlassian Migration Assistant moves your Jira Data Center (DC) projects to Jira Cloud. While issues, attachments, and most project data are transferred correctly, the OSLC Connect for Jira integration data is not — links between Jira issues and external tools (requirements, test cases, architecture elements, etc.) still reference DC-specific internal IDs and URLs that no longer work in Cloud.

This tool finds all affected resources, looks up their new Cloud identifiers using the Atlassian mapping service, and restores the data so that the OSLC integration works again in Jira Cloud.

What data is handled

2. How It Works

The process follows a fixed sequence of steps. The Indexer and the Updater are the two main programs in this package.

3. Prerequisites

Software & environment

Project associations: remote applications must be registered as friend applications

Jira DC: Basic authentication must be enabled

Supported databases (for database mode)

When running the Indexer in database mode, the Jira DC database is accessed directly. The following engine is supported:

Network connectivity

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

• Jira DC REST API (typically port 8080 or 443) — not needed in database mode with a CSV mapping file
• Jira DC database server (database mode only — port depends on the engine)
• 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.

0 Meet the Prerequisites

1 Prepare Your Configuration Files

1. Open config/cloud.properties and fill in your Jira Cloud tenant URL, service account credentials, Cloud site ID, and broker URL.
2. Open config/rest.properties and fill in your Jira DC base URL and credentials. It is needed in REST mode, and in database mode unless you provide a CSV mapping file with --idmappings.
3. If you plan to use database mode (recommended), also open config/db.properties and fill in your Jira DC database connection details.

2 Run the Indexer

Open a terminal in the folder where this package is installed and run one of the commands below. The Indexer will load the DC→Cloud ID mapping table first, then read OSLC data from Jira DC, and finally write one Excel file per project into the output folder you specify.

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

Index all migrated projects — database mode

Windows:

bin\index.bat --db config\db.properties --idmappings config\rest.properties --cloud config\cloud.properties --all-projects --dir output\

Linux:

bin/index.sh --db config/db.properties --idmappings config/rest.properties --cloud config/cloud.properties --all-projects --dir output/

Index all migrated projects — database mode with CSV mapping file

bin\index.bat --db config\db.properties --idmappings path\to\mappings.csv --cloud config\cloud.properties --all-projects --dir output\

Index all migrated projects — REST mode

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

Index all migrated projects — REST mode with CSV mapping file

bin\index.bat --rest config\rest.properties --idmappings path\to\mappings.csv --cloud config\cloud.properties --all-projects --dir output\

Index specific projects only

bin\index.bat --db config\db.properties --idmappings config\rest.properties --cloud config\cloud.properties --projects PROJ1,PROJ2 --dir output\

All available options

Which projects are indexed

The projects of the migration files already in --dir are always indexed again, so that a re-run keeps them up to date. --projects adds projects to those: with --projects PROJ1 and an existing file for PROJ2, both are indexed. When --dir already holds migration files, neither --all-projects nor --projects is needed. To index a single project, use a --dir holding no file of other projects.

Exit codes

Both the Indexer and the Updater exit with 0 on success, 1 when the run fails, and 2 on invalid arguments.

Output

After the Indexer finishes, you will find one Excel file per project in the output folder. Projects with no migratable resources produce no file and are skipped and logged. Each file is named jira$<PROJECT-KEY>$<DC-PROJECT-ID>$migration.xlsx.

output/
  jira$PROJ1$10000$migration.xlsx
  jira$PROJ2$10001$migration.xlsx
  ...

Each file contains one worksheet per resource type: remote_links, gc_versions, project_associations, and linktype_deliverables.

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

You can customize config/logback.xml with a text editor at any time:

• Change the log level by editing the level attribute on the <root> element (e.g. INFO → DEBUG for verbose output).
• Change the log file location by editing the LOG_LOCATION property (default: ${user.home}/oslc-connect-jira-cloud-migration/logs).
• Remove <appender-ref ref="FILE"/> inside <root> to disable file logging and keep console output only.

3 Review the Excel Files

Open the generated Excel files and review the results before running the Updater. Each row represents one resource 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. a link that should not be restored).
• Set to REPROCESS to force the Updater to re-post a record even if it was previously completed successfully.

4 Run the Updater

The Updater reads the Excel files produced by the Indexer and sends most indexed data to Jira Cloud and the OSLC Connect broker. If linktype_deliverables were indexed, there will be a .properties file generated in the --dir folder per indexed project; this file(s) must be deployed in the Tomcat server manually. See manual step below for details. The outcome of each row is written back into the same files, so you always have a full audit trail.
Note: depending on the project size, this may be a long operation. It's been observed to take up to 40 minutes when there are around 10K links to fix.

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

Run the Updater — Windows (all projects)

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

Run the Updater — Linux (all projects)

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

Update specific projects only

bin/update.sh --cloud config/cloud.properties --projects PROJ,DEMO --dir input/

Verify without posting (dry run)

Use --verify to parse and validate all input files without sending any update. It also checks that the Cloud credentials can administer every project and that the remote applications the projects are associated with are registered as friends in the broker; projects failing a check are reported and skipped. Useful to check the state of the working directory before committing updates. Note that:

• If the friend applications registered in the broker cannot be fetched while processing a project, its friend check is skipped with a warning and the project passes. The warning tells this case apart from missing friends:
  • could not fetch the friend applications registered in the broker: <reason> — skipping its friend registration check: the broker could not be queried (the reason gives the HTTP status or the error). The check is inconclusive: fix the cause and run --verify again.
  • <n> friend application(s) not registered in the broker: [<urls>]: the friends were fetched, and the listed applications are missing. The project is reported and skipped; register them as friends in the broker. An association URL that cannot be parsed is listed there too.
• No .properties deliverable file is written: its content is logged instead.
• A run without --verify does not make these checks.

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

All available options

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 records that could not be posted — check the status_detail column for the error and consider re-running the Updater after resolving it.
• Open Jira Cloud and navigate to some issues having remote links in a migrated project. Confirm that OSLC remote links are displayed and resolve correctly to the expected external resources. If linktype_deliverables were indexed/updated, verify issues using a Global Configuration also resolve to the expected versioned remote artifact. One way to quickly find issues having remote links is using the advanced (JQL) search in Jira Cloud. Pick some issue ids from any of the Excel files (from the issue_id column in the remote_links tab) and use them in the Jira Cloud Search work items page. Select the JQL mode and type id in () in the input field putting the issue ids in the parenthesis separated by commas.
• Check that project version associations with Global Configuration streams are restored and visible from the OSLC Connect broker’s project administration menu.
• Confirm that the OSLC Connect project associations are active, meaning the expected link types (e.g. "Implements Requirement") are available when creating links from issues.

Appendix

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

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