Recovering from importURLMappings errors

This topic describes recovery procedures for errors with the importURLMappings command.

If an error occurs while running importURLMappings, you can check the JazzInstallDir/server/repotools-jts_importURLMappings.log file.

You missed a mapping entry in your mappings file

If you discover that your original mappings file was missing an entry, such as a source-target pair for one of the IBM® Engineering Lifecycle Management (ELM) applications, take the following steps:

Shut down your server.
Create a new mappings file with just the missing entry.
Apply the new mappings file by rerunning the repotools-jts -importUrlMappings command.

You made a mistake in the target url of a mapping

If you made a mistake in a target url, apply the following corrective procedure. Corrections are cumulative, that is, they can happen at any time as long as the server has been shut down. You can make these corrections for more than one entry, but you should only add entries for mistakes. Those urls that you think mapped correctly should not be included. Assume you have the following entry in your original mappings file:

...
source=https://myOriginalUrl
target=https://myTargetUrlWithATypo
...

Shut down the server.
Create a new mappings file with the corrective mapping. Do not add this entry to the original mappings file. The entry could look like this:
```
source=https://myTargetUrlWithATypo
target=https://myCorrectTargetUrl
```
Apply the new mappings file by re-running the repotools-jts -importUrlMappings command.

You made a mistake in the source url of a mapping

The process is similar to the previous section, but slightly more complicated because you have to perform two corrective mappings separately. Assume you have the following entry in your original mappings file:

...
source=https://myOriginalUrlWithATypo
target=https://myTargetUrl
...

Create a new mappings file with the following corrective mapping. The purpose of this mapping file is to move the target, myTargetUrl, out of the way.
```
source=https://myTargetUrl
target=dummy://aDummyUrl
```
Apply the new mappings file by rerunning the repotools-jts -importUrlMappings command. Apply the correct mapping as follows:
```
source=https://myOriginalUrl
target=https://myTargetUrl
```

Do not try to combine these mappings in one file. The above corrective mappings have to be applied separately so that the system can correct itself without ambiguities.

You accidentally reversed the source and target in the mapping file

For example, your starting position is this:

...
source=https://myTargetUrl
target=https://mySourceUrl
...

Important: This scenario is only recoverable via the general recovery procedures.

To remedy this situation, you will have to follow the general recovery rules. The problem is that such a mapping expresses that the application at https://myTargetUrl also lives at https://mySourceUrl. Because this is where your application already lives, it introduces an ambiguity that cannot be undone.

You made a syntax error in the mapping

Correct the error and run importURLMappings again.

Command gives warning CRJAZ2425W

This warning indicates that the mapping event file did not contain any new mappings. This can happen if the same mapping file is imported twice or if the original generated mapping event file was not updated to specify the target URLs. Verify that the mapping file argument is pointing to the correct file and validate the file contents.

Command shows CRJAZ2197E message

There are errors in the importURLMappings log with a CRJAZ2197E, message or the CRJAZ2197E message appears when you start the server after running importURLMappings.

This message indicates The public URI for this server has already been set to https://jts.source.example.org:9443/jts. It cannot be changed to https://jts.target.example.org:9443/jts after the server has been configured. If the server has moved to a new location at https://jts.target.example.org:9443/jts, follow the instructions to rename the server.

Whenever importURLMappings fails, it should revert the URLs in the JTS teamserver.properties back to their original values. If it does not, you can manually update the teamserver.properties to contain the original URL and rerun importURLMappings or restart the server.