Resolving Issues Connecting to DOORS Classic
Note that since the publication of this article, Jira has dropped support for Internet Explorer 11. This prevents a proper integration of DOORS Classic with OSLC Connect for Jira.
Connecting DOORS Classic to Jira is most situations a standard procedure with a high degree of success. However, it has been observed that when errors occur in the connection between DOORS and Jira, they can be difficult to diagnose. The issue with diagnosing issues is both due to the error reporting in DOORS Classic and the type of common errors observed. The following is a guide to help support diagnosing and resolving the issues with connecting DOORS to DNG. Included here are some common errors and recognition criteria.
This guide is recommended as a companion to the common friending guides. It will not restate the common issues of friending and focus on only DOORS-specific challenges.
Friending from Jira to DOORS
Friending from Jira to DOORS has the standard OSLC related issues of visibility to the DWA server and standard network challenges. The standard friending guide should resolve any challenges.
The unique issues with DOORS have to do with the approval of the Friending. This activity is performed within the DOORS Client. Pay attention that the approval is in the configuration of the Jira Consumer.
And of the consumers that are not approved will fail in the connection.
Within the Friend management in the Jira administration, you will see this status being updated. Make sure you check this and if needed approve the key in DOORS Client.
Beyond this unique need to use the DOORS Client to approve the key, standard Friending evaluations should be used.
Friending from DOORS to Jira
Friending from DOORS to Jira has introduced more difficult issues due to the uniqueness of the DOORS Classic architecture. What is unique about DOORS Classic that we have seen cause challenges in debugging and resolving include.
Client tooling for Friending (instead of the server application)
Dependence on the Internet Explorer web-components for the DOORS Classic Client
Limited logging and unspecific error reporting
Each of these issues can cause challenges in getting the DOORS connection working in your environment. Use this guide to verify the expected behavior and pinpoint the issues that need to be resolved.
The General Friending flow with DOORS Classic
To understand where there are issues in the friending it is helpful to understand the basic sequence of events when a user attempts to friend Jira.
When creating a Friend, we are adding a new Server to the registered server list with this basic dialog in DOORS.
When a user clicks ‘Register’ a series of events occur
The rootservices document is downloaded and accessed
The Oauth services are read from the root services document
The application will attempt to request a token in the Oauth services with the Consumer Key and Secret
The application will attempt to get an access token and prompt for your Jira credentials
The application will download the catalog to understand the Jira projects you are authorized to see
At any point within this chain of events the steps fail (for many different reasons) the user will see the following error:
What is a challenge is that this is not precise on the cause of the issue. The good news is that we can add some precision via some simple steps.
Note: Adding the server anyway will rarely address any issues. We recommend that you follow the guide below and have a clean friending as without this you will have additional issues.
Pinpointing the Issues with your Error
Following are the steps you can follow to identify your errors' rough source and how to engage our support team for more guidance.
Verify the Location of the rootservices is accessible
The first step in creating a friend is understanding the services in the root services documents. If the failure message comes up without prompting a user's authentication you likely have issues accessing the rootservices document.
This can be obvious with a long delay (several seconds) before we see a response. This is usually an excellent indicator of a location error.
Since you are using your client application to access the artifact we need to verify connectivity to the rootservices document. In a fresh browser application, or using a tool such as curl, you should attempt to download the root services document.
Example curl command → curl -v https://jira-7-detroit.sodius.cloud:8443/rest/oslc/1.0/rootservices
With either browser application or the curl command, we are looking for an XML document called rootservices.rdf. It will look similar to the following.
If this is what you receive, it is most likely that the location is successfully defined. However, we may need to return to this later depending on security protocols (certs, tls levels, etc.)
If you are not able to access this document, please verify that the URL is correct. You may need to work with your network team to address
DNS Name resolution (unable to find the server)
Port forwarding mismatch
Firewall issue for a server or port
If you are requested for a password, you likely have an SSO issue on Jira, and you must review the whitelisting rules in the OSLC Connect for Jira guide.
Once this is resolved, we can move on to the next step.
Definitive proof of successful Access
If you want to check for access to the rootservices document on Jira, you can review the atlassian-jira-http-access.log
You should observe access to the document similar to the following:
10.100.99.2 i1243x1856646x1 [27/Feb/2021:20:43:06 +0100] "GET https://jira-7-detroit.sodius.cloud:8443/rest/oslc/1.0/rootservices HTTP/1.1" - - - - -
The important point is to see the time of the request being the same as your DOORS Friending attempt and to see the IP address being your local machine IP (this unique for DOORS Classic since most all other OSLC Tools do these request from the Server (and logs the server IP Address)
Verify your Key and Secret
If we are confident that we are downloading the rootservices document but not seeing a Jira web-login prompt, we are most likely have a key-secret issue. We recommend the following steps to rule out possible issues.
Try it Again
The most common issue is either mistyping or miscommunicating the key and secret. The best resolutions are to
Re-enter the key and secret. Remember to check for prefixes or trailing spaces that should be removed.
Re-create a key and secret. If you still have issues try generating a new key and secret in Jira.
Hopefully, that resolves the issue; if not, continue to the next step.
Try it with another Application.
Possibly there is an issue with DOORS (or DOORS’ connection), or simply we are communicating wrong. One of the best ways is to use another application to verify the Friending to validate the key and secret.
The most flexible is the Jira friending itself. We can verify key and secret immediately. Use the standard friending but reuse the existing option, like below.
If we see errors like the following, we should create a new consumer key in Jira and try again.
In most cases, we see the following, and we know the key is good, and we can explore deeper.
At this point, we recommend removing the Jira friend as it has validated the key and secret.
Check the Log
The last step is to check the log to see if our request is actively making it to Jira. To do this, we must both configure the logging as well as download the Jira logs.
To configure the logs, you will need to set the logging level.
As Admin go to System → Logging and Profiling
Go to the Configure default loggers.
Add ‘com.sodius.oslc.server.services’ to DEBUG level
Once you do this, we recommend marking the logs.
Once this is done, go back to your DOORS Client and attempt the Friending again.
Return to the Jira Admin and download the logs.
In the logs, look for the atlassian-jira.log file. We are looking for the /rest/oslc/1.0/oauth/requestToken from your client ip address.
A successful request looks like the following:
2021-02-27 16:48:34,303 https-jsse-nio-8443-exec-10 DEBUG anonymous 1008x1854263x1 - 10.100.99.2 /rest/oslc/1.0/oauth/requestToken [c.s.o.server.services.AccessLogFilter] "POST /rest/oslc/1.0/oauth/requestToken" [Accept="*/*", Authorization="OAuth realm="JIRA",oauth_consumer_key="MyKey",oauth_nonce="21",oauth_signature="2a60cdJ8Wq4c8JCTH%2BlYRIGnaOE%3D",oauth_signature_method="HMAC-SHA1",oauth_timestamp="1614440915",oauth_version="1.0"", Content-Type="application/x-www-form-urlencoded;charset=UTF-8"] 200 [Content-Type="text/plain;charset=UTF-8"]
We are looking to confirm the source IP address, the Authorization header's contents, and there are no error messages.
The types of error that we can see here and are looking for
Clock skew issues (client/server have differences in time that affect the token expirations)
Missing headers (stripped by network appliances such as load balancer or proxy)
No appearance of the requestToken request from DOORS (blocked content from DOORS Client in your network)
Please engage our support team to point to where the issue is likely and where you need to do updates.
Verify Authentication to Jira
Once the rootservices has been downloaded, and the consumer key and secret have successfully negotiated the token request, DOORS wants to make a catalog request. This is a step we typically don’t see in the friending flow, but the DOORS client does this to validate that it can request an access token and access your list of projects.
The ‘Collaboration Links’ that we assign in this same dialog require authentication and access to the catalog, making sense that it is done here.
If we fail this final step of authentication, we have technically completed the traditional Friending flow. However, DOORS will restrict the access of links from these friends (including links we created from Jira) as an attempt to keep errors occurring in both DWA and the DOORS Client. This is why we recommend against the ‘Add Server Anyway’ option because you will have issues in operation.
We observe two styles of issues at this stage; embedded Internet Explorer issues and Authentication service issues.
IE Issues
The DOORS Client uses Internet Explorer as its embedded web-client. This is a long legacy to the application and introduces a challenge in all OSLC tools that DOORS connects. This is because most applications have dropped to Internet Explorer support as a browser due to capability and security issues. This is especially true of Jira, which ended official support in their 8.5 release. However, for most users, the operation with IE is still compatible in critical operations needed for OSLC.
Login Issues
Issues with the login prompts are most significant. Note, the traditional login prompt has seen consistent support for IE through 8.13 without issue.
However, users have had the freedom to extend/modify the login dialog in their Jira instance. What this introduces is javascript that is incompatible with IE and makes the login dialog rendering impossible. If this happens, you will see IE script error messages that halt the dialog's operation, which means you can’t complete the login from DOORS to Jira. When this occurs, you cannot complete the friending, and you will not be able to use OSLC functions.
We recommend you explore your Jira team to evaluate IE support of the login dialog.
We also encourage you to engage with IBM support to indicate that you require modern browser support in DOORS Classic. While they have yet to commit to dates to replace the embedded IE browser, many customers are requesting it, and we encourage your voice in that discussion.
Other Dialog Issues
The other places we can see IE issues are on the Jira artifact selector and creation dialogs. While these are rare, they can restrict the workflow. If this does arise, we recommend the workaround of creating links only from Jira (as you can still use drag-n-drop with the DOORS client).
Authentication Service Issues
The remaining issue observed is the add-on authentication services in Jira (such as Single Sign-On). If the login activity is triggering without IE issues, but no authentication occurs, we would expect this to be the issue.
We encourage that you review the SSO guide to make sure the endpoints for Oauth are whitelisted. Additionally, you can review the Atlassian-jira.log to ensure that we see a sequence where an accessToken is successfully obtained, and the catalog is attempted with your user id similar to the following.
2021-02-27 16:48:53,240 https-jsse-nio-8443-exec-7 DEBUG anonymous 1008x1854299x1 fbdfso 10.100.99.2 /rest/oslc/1.0/cm/catalog [c.s.o.a.j.server.servlet.CredentialsFilter] OAuth token, trying three legged validation...
2021-02-27 16:48:53,241 https-jsse-nio-8443-exec-7 DEBUG anonymous 1008x1854299x1 fbdfso 10.100.99.2 /rest/oslc/1.0/cm/catalog [c.s.o.a.j.server.utils.Services] User patricia authorized!
2021-02-27 16:48:53,242 https-jsse-nio-8443-exec-7 DEBUG patricia 1008x1854299x1 fbdfso 10.100.99.2 /rest/oslc/1.0/cm/catalog [c.s.o.a.j.server.servlet.LicenseFilter] GET /rest/oslc/1.0/cm/catalog
We encourage reaching out to our team if you have any questions on this, as it is a place where we can give further guidance.