FAQs

This topic lists commonly asked questions about synchronizations and connections.

Why can't I delete a connection or data source?

Connection and data source details, such as the server or projects, define the links between the corresponding items in the synchronized products. If these details are removed, the link will be broken.

Solution: Only delete a data source and connection if they are not being used for a synchronization.

How can I use a connection whose type name has changed?

You can use a connection that uses types whose names were changed by the endpoint admin. For example, let's assume that you have a Jira custom type Error that was renamed to Bug-RSI. If you take no action, all connections that include the original type will fail.

Solution: Continue using the connection, but rename the type within the connections.

To fix the connection:

Create a copy of each connection that included the original type name. You can do this with the user interface, as described in Create a connection.
Alternatively, use the import /export mechanism:
1. Export the connect.xml file of the original connection and open it for editing.
2. Change the connection name.
3. Replace all occurrences of the original type name with the new type name.
4. Import the modified connect.xml file. For details, see Cloning connections.
Import the cross references from the old connection to the new one:
- Delete it manually as described in Manage cross references.
- Run the CopyXRefs batch script . For details, see Batch utility scripts.
Delete the old connection:
- Delete it manually as described in Manage cross references.
- Run the DeleteConnection batch script . For details, see Batch utility scripts.
Start the new connection. For details, see Start or stop connections.

Why do I see duplicates in the synchronized results?

I created a new connection, and I am seeing duplicates in the synchronized results for this connection.

Solution: The reason for this is because the projects were mapped twice—once in Common Projects, and again in type-specific project maps. To prevent the duplication, deactivate Common Projects. Open the connection for editing and go to the Projects and Rules page. In the Common Projects area, hover over the Enable/Disable button and click the Disable project synchronization button .

Type-specific project mapping provides you with all the necessary mapping capabilities. For example, with type-specific project mapping, you can set synchronization criteria for each type/project tuple, indicating the artifacts that should get loaded by Connect into each syncset. With Common Projects, you do not have this level of control.

What is the significance of master and target in a connection?

Several levels of information are used to detect changes and to determine which side made a change most recently. In the rare case where this information is insufficient for determining which side's changes should be applied, the master is used. Most products provide sufficient details, making this designation almost redundant.

Can I rename an ALM Octane or an ALM/QC project, without breaking my synchronization?

Yes. Stop all connections, and stop the Connect service on the machine. Rename the ALM/QC project and restart the Connect service.

If the renamed project was used as a data source (sample) project, update the data source's project name.
If the project is being used by a connection in Common Projects, double-click on the old project name, expand the project list drop down, and select the new project name. Save the changes and run the connection.
If the project is being used in a type-specific project map, click the Change Project Pair for this Type Rule button . Expand the project list dropdown and select the new project name. Save the changes and run the connection.
If you are synching with Jira, after you change the project name, you must also replace the issue keys. When you rename a project, Jira generates a new project key and updates the issue keys to use the new project key. To replace the issue keys:
1. Export the cross references for the connection. For details, see Manage cross references.
2. Perform a search and replace for old issue keys (using the old project key) to new issue keys (using the new project key).
3. Re-import the modified cross references. For details, see Manage cross references.
4. Test and verify the connection and make sure that the newly created keys match the keys in the Jira server.

How can I remove orphan cross references?

I have deleted artifacts at one of the endpoints. How can I remove the orphan cross-references from the database?

Solution: The following solution applies to the following endpoints – ALM/QC, ALM Octane, Jira, Azure DevOps, Rally, and Version One:

Run the StopAllConnections script to stop all connections. For details, see Batch utility scripts.
Run the Purge script to purge the data.
Stop the Connect service.
Archive the data folder into a Zip file, and back it up.
Run the ClearWaterMarks script with the following options to remove the watermarks (remove the ‘rem’ from line 21, save, and run). This deletes all cross references which no longer exist as artifacts in Jira or ALM/QC.

rem "%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcClearWaterMarks.jar" "%CONNECT_PATH%" removenulls removemismatches
Restart the Connect service and log in to Connect.
Select the connection. Click the connection's cogwheel-shaped button , Modify Connection, to open the action menu. Choose Export Cross References.
Open the resulting XML file. Perform a spot check and verify that the stale and deleted cross references are no longer present.
Run the StartAllConnections script to restart all of the connections.

Can I move stories/defects across projects?

Yes, depending on the product. For example, Rally understands and describes when a Story has moved from one project to another.

How is data encrypted for the Derby database?

Connect does not encrypt the Apache Derby database or its contents.

No private data is stored in the database. It contains data sources with their properties, such as endpoint URLs, type and field information, connections, rules, syncsets, user maps (if configured), audits of success or failure, and the cross reference IDs or keys for the synchronized artifacts.

However, the data source user service account passwords and client secrets are stored using a Base64 encryption, a two-way RC4 encrypted hash, and with a private seed.

When an item fails to synchronize, does it retry?

Yes. Any failure to synchronize an item is tracked and recorded. The synchronization is retried twice. If it continues to fail, it stops trying. After this point, if a change is detected for the item, for example if you fixed a bad status value, it attempts to synchronize again. In addition, if you clear the watermarks for a connection, the failure state is also cleared, and Connect resumes its attempts to synchronize.

How are embedded images synchronized?

In some systems, such as ALM Octane and Jira, images embedded in memo fields are saved as attachments. In other systems, such as Azure DevOps, embedded images are not saved as attachments.

When an Azure DevOps item with an embedded image is synchronized with ALM Octane, for example, the image is saved in ALM Octane as an attachment. The attachment from ALM Octane is then synchronized back to Azure DevOps and appended to the original item as an attachment. Both of these operations are completed within the same connection iteration.

Jira-specific questions

This section lists several common question asked by Jira users.

Why is the JIRA cloud column "Reporter" missing?

For any field to be displayed in Connect, it must appear in the Create screen of:

the sample project and board, selected in the data source.
every Jira project being synced to or from Connect.

Admins must follow all of the instructions described in Prepare Jira for synchronization.

Which Jira authorization methods are supported?

The Jira connector supports five authorization methods:

User & Password, non-OAuth authorization (email and API key on Atlassian Cloud).
Keycloak Code Flow OAuth authorization.
Azure DevOps Code Flow OAuth authorization.
Password Grant Flow OAuth authorization.
User Supplied Refresh Token OAuth authorization.

For details about the OAuth-based authorization schemes, refer to the Jira connector readme.

Each method uses specific parameters that are required for the authorization, provided your Jira server supports that method. If authorization fails, this is most likely an indication that your Jira server does not support your authorization method.

To determine which OAuth authorization method is supported by your organization:

Access your OAuth documentation and search for a code (for example, in Java, C#, C++, and Jython) that shows how client applications communicate with your OAuth server.
Determine the Grant Flow mechanism: What method it supports, what parameters it expects to be sent, and what causes it to return an access token.
If you have other 3rd party applications using OAuth to access your Jira server, consult the app owners and determine what string was sent to the OAuth server, the response, and how it handles refreshes.
Install the 64-bit Postman utility, preferably on the Connect server machine.
Using Postman, issue a POST command to your OAuth server with the required parameters.
Verify that it returns a valid access token in the challenge/response. If the token is valid, redirect the POST command to the Jira server, passing this access token. Make sure that it is accepted by the Jira server and that it returns a 200 code, indicating Success.
Once you have established the appropriate Grant Flow sequence with Postman, select one of the four OAuth authorization schemes from the dropdown in Jira.

Can I change my target data source from Jira Server (on-premises) to Jira Cloud?

Yes. To ensure that cross references are maintained and to avoid data duplication, perform the following steps:

Create a new cloud data source.
Stop the on-premises connection and deactivate it.
Export the on-premises connection to an XML file, for example, connect.xml. For details, see Export data.
Open the XML file for editing and change the connection name and the Jira data source name. Save the file.
Import the modified XML file. For details, see Import data.
Copy the original cross references to the cloud connection in one of the following ways:
- Run the CopyXrefs script located in the utilities folder. For details, see Batch utility scripts.
- Manually copy the cross references:
  1. Export the cross references from the on-premise connection. For details, see Import/export use-case.
  2. Copy and paste the cross references from the on-premises xref.xml to the cloud xref-template.xml. The XML files are add blocks.
  3. Verify that the cloud XML schema is valid by opening it in a browser such as Chrome or Edge. The browser indicates any errors in the XML code.
  4. Import the cross reference template file (now with all the cross references added). For details, see Import/export use-case.
Export the cross references from the cloud connection. Perform a spot check to verify that the cross references are correct.
Start running the cloud connection.

How do I prepare trace logs for Support?

To troubleshoot a specific, reproducible issue, gather debug information through a trace log, and send it to Support. You first need to turn on trace-level logging and then repeat the steps that caused the issue. For details, see Gather debug information.