OSLC Connect for Jira Cloud

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.

polarion.baseUrl=https://polarion.example.com/polarion
polarion.timeoutMs=30000

# Personal Access Token, sent as: Authorization: Bearer <token>
polarion.token=...

# User name and password. Required for associations (form login).
# For links, used as Basic authentication only when polarion.token is absent.
#polarion.username=...
#polarion.password=...

0 Meet the Prerequisites

1 Prepare Your Configuration Files

1. Open config/polarion.properties and fill in your Polarion base URL and credentials (a Personal Access Token, or a user name and password; associations need the user name and password).
2. Open config/rest.properties and fill in your Jira DC base URL. It is used to identify the links and associations that point at Jira DC. Fill in the user name and password too if associations are indexed without --idmappings; otherwise they are not used but must be set.
3. Open config/cloud.properties and fill in the broker URL, used to build the new link and association targets, and the Jira Cloud site URL (rest.baseUrl), used to fetch the ID mapping for associations. The other properties are not used but must be set.

2 Run the Indexer (index-polarion)

Open a terminal in the folder where this package is installed and run one of the commands below. The Indexer connects to the Polarion server to discover the OSLC links held by the workitems of each project and the projects’ Linked Data Associations, and writes one Excel file per project into the output folder.

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

Run the Indexer (all projects) — Windows

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

Run the Indexer (all projects) — Linux

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

Run the Indexer (specific projects) — Windows

bin\index-polarion.bat --polarion config\polarion.properties --rest config\rest.properties --cloud config\cloud.properties --dir output\ --projects proj,demo

Run the Indexer (specific projects) — Linux

bin/index-polarion.sh --polarion config/polarion.properties --rest config/rest.properties --cloud config/cloud.properties --dir output/ --projects proj,demo

Links only (no ID mapping, a token is enough) — Windows

bin\index-polarion.bat --polarion config\polarion.properties --rest config\rest.properties --dir output\ --all-projects --resource-types links

Links only (no ID mapping, a token is enough) — Linux

bin/index-polarion.sh --polarion config/polarion.properties --rest config/rest.properties --dir output/ --all-projects --resource-types links

Associations only, ID mapping from a CSV file — Windows

bin\index-polarion.bat --polarion config\polarion.properties --rest config\rest.properties --idmappings output\id-mappings.csv --dir output\ --all-projects --resource-types associations

Associations only, ID mapping from a CSV file — Linux

bin/index-polarion.sh --polarion config/polarion.properties --rest config/rest.properties --idmappings output/id-mappings.csv --dir output/ --all-projects --resource-types associations

All available options

Output

After the Indexer finishes, you will find one Excel file per project in the output folder, named polarion_<projectId>_migration.xlsx. For example, with projects proj and demo:

output/
  polarion_proj_migration.xlsx
  polarion_demo_migration.xlsx

Each file contains a links worksheet listing the OSLC links pointing to Jira DC issues, and an associations worksheet listing the Linked Data Associations pointing to Jira DC projects. See the Appendix for the full column reference.

Files are only created when at least one link or association to migrate is found for the project. Projects with nothing to migrate produce no output file.

3 Review the Excel Files

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

4 Run the Updater (update-polarion)

The Updater reads the Excel files produced by the Indexer and, for each workitem, replaces the Jira DC link targets with their Cloud equivalents on the Polarion 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-polarion.sh bin/update-polarion.sh

Run the Updater (all files) — Windows

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

Run the Updater (all files) — Linux

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

Run the Updater (specific projects) — Windows

bin\update-polarion.bat --polarion config\polarion.properties --cloud config\cloud.properties --dir output\ --projects proj,demo

Run the Updater (specific projects) — Linux

bin/update-polarion.sh --polarion config/polarion.properties --cloud config/cloud.properties --dir output/ --projects proj,demo

Validate the files without updating

Use --verify to parse and validate all input files without writing anything to Polarion. Associations are still loaded, so the Polarion user name and password are needed: for each project, the list that would be saved is written next to its workbook, as polarion_<project>_serviceproviders.xml. It has the format of the file Polarion keeps the associations in, <project>/.polarion/oslc/serviceproviders.xml, and holds the whole list: review it, or put it in place of that file to apply the change yourself. Useful to check the state of the working directory before committing updates.

Validate the files without updating (all files) — Windows

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

Validate the files without updating (all files) — Linux

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

All available options

What the Updater does for OSLC links

The Updater processes each workitem through a GET–replace–PUT cycle on the Polarion server:

1. GET workitem — fetches the current RDF/XML representation of the workitem and its ETag header.
2. Replace links — in the fetched RDF/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 workitem 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 RDF/XML body and an If-Match header carrying the ETag from the GET response.

All the links of one workitem are grouped and sent in a single request, whatever their types. Because of the If-Match header, a workitem someone else changed in the meantime fails with 412 instead of silently overwriting their edit; the rows of that workitem are marked FAILED_UPDATE.

What the Updater does for associations

For each project, the Updater loads the project’s Linked Data Associations, repoints the ones the associations sheet names to the Cloud service provider, and saves the list back. See Linked Data Associations for how the project is protected along the way.

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 links that could not be migrated — check the status_detail column for the error and consider re-running the Updater after resolving it.
• Open some of the migrated workitems in Polarion and confirm that their links to Jira now point to the Cloud-side OSLC Connect broker instead of the old DC instance.
• For associations, create a link to Jira Cloud from a workitem of each migrated project.

Known Limitations

OSLC links to unmigrated issues are not detected

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-polarion will overwrite the original DC link in the Polarion workitem 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 Polarion workitem (e.g. ALPHA-1 from .../cm/change-request/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 Polarion workitem, 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 Polarion workitem 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 Polarion workitems 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

Configuration

Missing required property

Missing required property: rest.username

The named property is missing or empty in rest.properties or cloud.properties. Some properties are not used by the Polarion commands but are still required when the file is loaded; any non-empty value is accepted. See Configuration Files.

Polarion credentials rejected at startup

No credentials configured: set polarion.token, or polarion.username + polarion.password
polarion.username and polarion.password must be configured together

At least one credential form must be configured in polarion.properties: a Personal Access Token, or both a user name and a password.

Associations need a user name and password

Linked Data Association work needs polarion.username and polarion.password: ...

Associations are indexed or updated, but polarion.properties holds only a token. Add polarion.username and polarion.password, or index links only with --resource-types links. See Linked Data Associations.

Indexing (index-polarion)

Indexing associations needs the DC->Cloud ID mapping

Indexing associations needs the DC->Cloud ID mapping: provide --cloud, or --idmappings.

Associations are indexed (the default) but neither --cloud nor --idmappings was given. Add one of them, or index links only with --resource-types links.

Unknown Polarion project(s)

Unknown Polarion project(s): Proj. Available: demo, proj

A project ID given with --projects is not advertised by the Polarion OSLC catalog, and the run is aborted. Project IDs are case-sensitive: use them exactly as listed after Available:.

index-polarion failed: HTTP … from …/oslc/services/catalog

index-polarion failed: HTTP 401 from https://polarion.example.com/polarion/oslc/services/catalog: ...

The OSLC catalog could not be read, so no project can be indexed and the run is aborted. A 401 or 403 means the Polarion credentials are invalid or not allowed; a 404 usually means polarion.baseUrl is missing the context path (e.g. /polarion).

No Polarion project to index

The OSLC catalog was read but advertised no project. Check that the Polarion account can see the projects to migrate (see Required permissions).

No workitem query capability found

[proj] No workitem query capability found, skipping

The project’s service provider does not advertise the unfiltered workitem query capability (a query base ending in /workitems/oslc.query/), so its links cannot be read. The project is skipped and no file is written for it.

Skipping link with no trailing ID

Skipping link with no trailing ID in target URL: https://jira-dc.example.com/...

The link points at Jira DC but its target URL does not end with an issue key, so it cannot be rewritten. The link is not written to the Excel file and stays unchanged in Polarion.

Failed to index project

[proj] Failed to index project, skipping

A Polarion request failed while reading this project; the logged exception carries the HTTP status and response body. The other projects are still indexed. An HTTP 401 or 403 means the Polarion credentials are invalid or lack read access to the project.

Updating (update-polarion)

broker.baseUrl is required

broker.baseUrl is required in cloud.properties for the update-polarion step.

Set broker.baseUrl in cloud.properties, including the context path (e.g. https://broker.example.com/oslc-connect-jira).

No Polarion migration files found / File not found

No Polarion migration files found in /path/to/output
File not found: output/polarion_proj_migration.xlsx

Check that --dir points to the folder written by index-polarion, and that the IDs given with --projects match the project IDs in the file names. A project with no migratable links has no file.

FAILED_UPDATE with status 412

The workitem was modified in Polarion between the Updater’s read and its write, so the write was refused rather than overwriting the other change. Re-run update-polarion: the workitem is read again and the rows are retried.

FAILED_UPDATE with status 401 or 403

The Polarion account cannot modify the workitem. Check that it has write access to the workitems carrying the links (see Required permissions), then re-run update-polarion.