--- version: "Working version" language: "en" --- # OSLC Connect Product Documentation ## OSLC Connect Product Documentation Welcome to the documentation. In this space, you will find detailed articles to help you set up, configure, and use our OSLC Connect for Jira, Confluence, and W... [Get started](https://docs.sodiuswillert.com/oslc-connect/latest/get-started.md) ### Featured * #### [Failed authentication or authentication loops](https://docs.sodiuswillert.com/oslc-connect/latest/failed-authentication-or-authentication-loops.md) Applies to Any OSLC application Problem User authenticates to the remote application, but the authentication does not appear to be working. While OSLC Connect ... * #### [Help us help you: on creating good Support Requests, reporting even better on Bugs, and suggesting awesome New Features](https://docs.sodiuswillert.com/oslc-connect/latest/help-us-help-you-on-creating-good-support-requests.md) Explaining what we are going through or expect as a user is almost an art. Determining what is the relevant information to share, and what is not, can be a dau... * #### [Help us help you: on creating good Support Requests, reporting even better on Bugs, and suggesting awesome New Features](https://docs.sodiuswillert.com/oslc-connect/latest/help-us-help-you-on-creating-good-support-requests.md) Explaining what we are going through or expect as a user is almost an art. Determining what is the relevant information to share, and what is not, can be a dau... ### Topics * #### [Get started](https://docs.sodiuswillert.com/oslc-connect/latest/get-started.md) * [OSLC Connect for Jira Cloud](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira-cloud.md) * [OSLC Connect for Jira Data Center](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira.md) * [OSLC Connect for Confluence Data Center](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-confluence.md) * [OSLC Connect for Windchill](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-windchill.md) * #### [About OSLC](https://docs.sodiuswillert.com/oslc-connect/latest/about-oslc.md) * [Understanding OSLC Architecture](https://docs.sodiuswillert.com/oslc-connect/latest/understanding-oslc-architecture.md) * [OSLC \& Security](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-security.md) * #### [Advanced Topics](https://docs.sodiuswillert.com/oslc-connect/latest/administration-how-to.md) * [OSLC General Support References](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-general-support-references.md) * [OSLC Connect for Jira Administration](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira-administration.md) * [IBM Support Questions](https://docs.sodiuswillert.com/oslc-connect/latest/ibm-support-questions.md) * [Siemens Polarion OSLC Configurations](https://docs.sodiuswillert.com/oslc-connect/latest/siemens-tools.md) * [OSLC Architectures](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-architectures.md) * [3 more pages](https://docs.sodiuswillert.com/oslc-connect/latest/administration-how-to.md) * #### [Troubleshooting](https://docs.sodiuswillert.com/oslc-connect/latest/troubleshooting.md) * [OSLC Connect tools](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-tools.md) * [OSLC Connect for Jira specific articles](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira-specific-articles.md) * [IBM specific articles](https://docs.sodiuswillert.com/oslc-connect/latest/ibm-specific-articles.md) * [Siemens specific articles](https://docs.sodiuswillert.com/oslc-connect/latest/siemens-specific-articles.md) * #### [Security Advisories](https://docs.sodiuswillert.com/oslc-connect/latest/security-advisories.md) * [Log4j 2021 vulnerabilities](https://docs.sodiuswillert.com/oslc-connect/latest/log4j-2021-vulnerabilities.md) --- version: "Working version" language: "en" --- # About OSLC Enabling real-time, cross-tool, efficient collaboration in the everyday life can be leveraged using Open Standard for Lifecycle Collaboration (OSLC). But what is OSLC exactly? What are its benefits? How does it work? What are the constraints? This section in the OSLC Connect products Documentation aims at taking you through what you need to know about OSLC before going ahead with our products. Navigate through each of these articles to learn more about OSLC: * [Understanding OSLC Architecture](https://docs.sodiuswillert.com/oslc-connect/latest/understanding-oslc-architecture.md) * [OSLC \& Security](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-security.md) --- version: "Working version" language: "en" --- # Accessing Custom Jira Fields via OSLC OSLC Connect for Jira supports the standard shapes for OSLC Change Management objects. This allows users to use the standard identifiers to extract values for reports, searches, or other integrations. However, what if you want to use custom Jira fields in your reports. How would you consider doing this? And how would your tooling understand this new attribute? The answer for this is Resource Shapes. In OSLC, this is the type definition for an object. This effectively describes the attributes and the types of attributes for a resource. In practice, this defines what attributes are available for an artifact for every Jira Issue in a particular Scheme. ## Updating the Jira Resource Shape The standard artifact shape attributes can be found in the OSLC Connect for Jira help. ( ). However, we know users use extended attributes so we enable users to extend the types and we will describe below how to discover the ids to access them with remote tools. With OSLC Connect for Jira, administrators can update the attributes included in the issue shape. This is done on a Jira Scheme level and modified in the Jira Administration for OSLC Connect. ![image-20250225-181307.png](https://docs.sodiuswillert.com/__attachments/a_da85ffee55b6bfb89fd77c176898e6552e54ca797507f66a2ba625a1785f0019/image-20250225-181307.png?cb=0a1eba5a70ed9b9795aabcf81f152d8d) On this page, users can add additional Jira fields in the issue shape. Note that not all fields are supported and presented on the Jira form. More details are defined in the product help → When this is updated, the next time the Shape is requested, or an artifact is requested, the extended attributes will be available for that scheme. If you have multiple schemes, each will need to be updated. With tools like Report Builder, you will access the attribute's name. For other tools, users will need to request and review the shape and artifact data to guide their tool definitions. ## Accessing the Resource Shape OSLC interactions are common web interactions. If a tool or a user wants to access a resource shape they only need to request the shape document and read the contents. Many tools will do this automatically to aid in reporting, however, we occasionally need to access these directly. When the remote tooling does not process the shape directly, users can use the features in OSLC Connect for Jira to review the shape of the resource. The "Show Resource Shape" button (on the bottom left of the page) will show the following style popup. ![image-20250225-181604.png](https://docs.sodiuswillert.com/__attachments/a_97ec17b76fd2b26abfd96cbedd06dbfd6077fab6d8183e523e4e8d62e87ee448/image-20250225-181604.png?cb=8e5e43655acab0e3c878af010d75738b) This provides access to the title and description of the artifact. The Property definition and type are used in reporting and accessing the artifact. For examples of this look to the next section. ## Accessing the Issue Resource OSLC interactions are common web interactions. If a tool or a user wants to access an issue resource they only need to request the document and read the contents. Many tools will do this automatically to aid in reporting, however, we occasionally need to access these directly. Once a user has the resource shape shown, they may review a specific artifact by using their Jira key. ![image-20250225-181915.png](https://docs.sodiuswillert.com/__attachments/a_e3928cd87bd3cdadccdda02d4250a5df97d0b7e6515ed8f907531892d11e93e8/image-20250225-181915.png?cb=60845457afc8a4c2098f7bd4fc8a87ab) Once selected the table expands to show that specific's resource's values. ![image-20250225-182003.png](https://docs.sodiuswillert.com/__attachments/a_9e0ed417afe6e6bea83a0a8db292e7fabf35c3bcd15120782de34a5bdcdfbb42/image-20250225-182003.png?cb=a13a4be5308ee9a998611f1ce19e6706) As well a user can download the resource in a native format like a reporting tool (json or rdf-xml). For example this is what the downloaded rdf-xml would be for this resource. You can see this includes the Jira artifact attributes and links. false POL2310-2 2024-03-06T14:21:58.428Z Medium POL2310-2 false 16.0 To Do Created from Polarion POL2310-2 false Story false 2025-02-25T18:28:16.63Z DP-429 ## Using this in Polarion Tables One of the main uses of this information would be to add Jira information to tables or reports in Polarion. All the existing documents are used to create the tables. However, if you were to add the Story Points information to the table, you would modify your configuration from the example to the following: Note the addition of the jira_x and the usage of the id information for Sprint using the jira_x prefix. To use 'jira_x' it must be added to the namespaces used in the OSLC Semantics in the Global Configuration of Polarion. Navigate to the Default Repository in Polarion and the Linked Data Semantics ![image-20220113-195508.png](https://docs.sodiuswillert.com/__attachments/a_d8d9c0a8d9ae39fce87d412850bedfeeda2bcc20036d6ef4c21e7c2d478e171d/image-20220113-195508.png?cb=711f75e66da17ed0d4ae7c00ffd945ba) Make sure 'jira_x' is defined in the namespace. ![image-20220113-195559.png](https://docs.sodiuswillert.com/__attachments/a_4093c75c8538896f06ddfd50f9fe4a2e6018ecce06e7f1a745645598892e9146/image-20220113-195559.png?cb=c2e7a9dbf67b6c37d37e6707f534f7cb) It should be as follows: --- version: "Working version" language: "en" --- # Adding OSLC Links Adding OSLC Links can be done via Scriptrunner. For unidirectional links (or links discovered by a remote tool like DNG) these can be done with the addition of a Jira Remote Link. The structure of those links are found in [Understanding OSLC Connect for Jira Link Storage](https://docs.sodiuswillert.com/oslc-connect/latest/understanding-oslc-connect-for-jira-link-storage.md) . For backlinks that are used on CM to CM artifacts or in repositories not using link discovery, this can be done via creating links on the remote resource. The example script below demonstrates both of these scenarios. In this script we are using a workitem key stored in the description of a Jira issue to create a local link to a Polarion artifact and creating the backlink on the Polarion artifact. Our initial state is without any links, but a simple workitem key in the description. ![image-20240403-181756.png](https://docs.sodiuswillert.com/__attachments/a_0adfcebdb948ed62529be27ea0094582ab1a963278fdc901c14111033770cf8c/image-20240403-181756.png?cb=6746483b3a40611450fac4968fad7d48) After executing the script, locally the Jira Remote Link is created (and takes on the OSLC dynamics) ![image-20240403-182018.png](https://docs.sodiuswillert.com/__attachments/a_8111112ab8f6ee487af7c063711c49fb2a870ba7f9a1fd79fd827d0328d25e9a/image-20240403-182018.png?cb=b3430f25de6c30950786d58cab990b05) And the backlink has been created in Polarion. ![image-20240403-182115.png](https://docs.sodiuswillert.com/__attachments/a_af4598d8422249ca0c04b0bebd5f73586b8051af4e227242190fd0eeb3723375/image-20240403-182115.png?cb=0164bd66717e7402ead546c0e542b21b) The following script is a sample for you to explore and build your own automation. Groovy import com.onresolve.scriptrunner.runner.customisers.WithPlugin import com.atlassian.plugin.PluginAccessor import com.sodius.oslc.core.process.model.LinkType import com.sodius.oslc.core.process.links.model.DirectedLink; import com.sodius.oslc.core.process.links.requests.AddLink; import org.eclipse.lyo.oslc4j.core.model.Link; import com.sodius.oslc.client.OslcClient; import com.sodius.oslc.client.OslcClients; import com.atlassian.jira.component.ComponentAccessor; import com.atlassian.jira.issue.link.RemoteIssueLinkManager; import com.atlassian.jira.issue.link.RemoteIssueLink; import com.atlassian.jira.issue.link.RemoteIssueLinkBuilder; @WithPlugin("com.sodius.oslc.app.jira") // Test mode disables the creation but runs all the checks boolean testMode = true; boolean jazz = false; // Get the Jira base URL def jiraRootUrl = ComponentAccessor.getApplicationProperties().getString('jira.baseurl') def targetBaseUrl = "https://polar-21r1-brest.sodius.cloud/polarion/oslc" // Set the local username to be logged as the action performing the work def userName = "patricia" // Set the remote user name and password def remoteUserName = "admin" def remoteUserPassword = "admin" def oslcConnectApp = "com.sodius.oslc.app.jira" def oslcConnectName = "Collaboration Link" // Metrics counters int createdLinks = 0; int issueCount = 0; log.info("Starting Sodius Link Creation") // This is an example of converting a description field key to a remote link. // The target in this example uses Polarion for simplcity of the URL formulation of the OSLC target // User customization can take place for more complex storage, URL composition and the like // The structure of this example is to ease understanding // Get the local Jira user def user = ComponentAccessor.getUserManager().getUserByName(userName) // Get the remote Client (assuming all links are to the same respository) - note jazz/IBM have different client connections // Updated based on Adaptavist guidance def userCredentials = ComponentAccessor.getComponent(PluginAccessor).getEnabledPlugin("com.sodius.oslc.app.jira").getClassLoader() .loadClass("org.apache.http.auth.UsernamePasswordCredentials") .getConstructor(String, String) .newInstance(remoteUserName, remoteUserPassword) def client = null try { if (jazz) { client = OslcClients.jazzForm( userCredentials ).create(); } else { client = OslcClients.basic( userCredentials ).create(); } } catch (Exception ex) { log.info("Unable to create a client. Exiting." + ex.getMessage() ) return } // Iterate through a Project and create local and remote links. (The JQL determines the scope) Issues.search('project = POL21R1 AND issuekey = POL21R1-1').findAll { issue -> issueCount++; // Fixed project key for the example def projectKey = "drivepilot"; // Use the description field to get the id of the object to link to (assumes only one artifact per description) def workItemKey = issue.description // Construct Polarion and Jira URLs String targetURL = "$targetBaseUrl/services/projects/$projectKey/workitems/$workItemKey" String jiraURL = "$jiraRootUrl/rest/oslc/1.0/cm/issue/$issue.key" log.info("Source of Link -> " + jiraURL); log.info("Target of Link -> " + targetURL); if (!testMode) { // Build and create link in remote tool (Polarion) DirectedLink directedLink = new DirectedLink() directedLink.setPropertyDefinition(LinkType.IMPLEMENTED_BY.getPropertyDefinition()); // This link type could be algorithmically determined or fixed directedLink.setSource( URI.create(targetURL) ) directedLink.setTarget(new Link(URI.create(jiraURL), issue.key)) def addLinkResponse = new AddLink(client, directedLink).call() log.info("Created Link in Remote Repository"); createdLinks++; // Build and create the local (Jira Remote Link) link in Jira def remoteIssueLinkManager = ComponentAccessor.getComponent(RemoteIssueLinkManager.class) def relationshipType = "implements requirement"; // This is the inverse relationship of the remote link and a textual description // Check if the link already exists before creating it def exists = remoteIssueLinkManager.getRemoteIssueLinksForIssue(issue).any { existingLink -> existingLink.url == targetURL && existingLink.applicationType == oslcConnectApp && existingLink.relationship == relationshipType } if (!exists) { def remoteLink = new RemoteIssueLinkBuilder() .url(targetURL) .title("$workItemKey") // This is the name shown before authenticating to the remote object .issueId(issue.id) .relationship(relationshipType) .applicationType(oslcConnectApp) .applicationName(oslcConnectName) .build() remoteIssueLinkManager.createRemoteIssueLink(remoteLink, user) log.info("Created Link in Local Repository"); } } else { log.info("Operating in test mode. No link creation") } log.info("Reviewed " + issueCount + " issues and created " + createdLinks + " links.") } --- version: "Working version" language: "en" --- # Advanced Topics You will find here how-to articles related to the deployment and the administration of SodiusWillert's OSLC solutions, namely OSLC Connect for Jira and OSLC Connect for Confluence. We also have more than a few articles dedicated to market solutions, such as IBM Engineering Lifecycle Management and Siemens Polarion. * [OSLC General Support References](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-general-support-references.md) * [OSLC Connect for Jira Administration](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira-administration.md) * [IBM Support Questions](https://docs.sodiuswillert.com/oslc-connect/latest/ibm-support-questions.md) * [Siemens Polarion OSLC Configurations](https://docs.sodiuswillert.com/oslc-connect/latest/siemens-tools.md) * [OSLC Architectures](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-architectures.md) * [OSLC Connect for Jira Developer Notes](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira-developer-notes.md) * [QM (XRay) Integration](https://docs.sodiuswillert.com/oslc-connect/latest/qm-xray-integration.md) * [OSLC Connect for Windchill Advanced Topics](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-windchill-advanced-topics.md) --- version: "Working version" language: "en" --- # Analyzing your TRS Activity with Python In the latest releases of OSLC Connect for Jira (4.1 and 5.1), there is a new option to download the TRS feed. We created this feature when collaborating with some customers on the load profile of their OSLC Enterprise. While doing so, we felt it would be valuable to show how this information can help you understand your Jira system better. ## Basics on TRS Tracked Resource Sets (TRS) are a way to allow a remote system to track artifacts. It provides the base list of artifacts to be monitored and a change log. The change log is a rolling list of changes for up to 7 days, including Creation, Modification, and Deletion events. The TRS interface is a REST API that returns XML pages listing elements. In the case of the change log, it also lists the associated event for each component. It is then up to the remote application to read the resources to keep its internal stores up to date. ## What we can analyze TRS does provide a valuable snapshot into the activities of a Jira system. We can observe change rates and change loads. This should allow an enterprise to understand the actions in their Jira system, as well as their impact on the IBM enterprise. It can also help detect suprises, like automations gone a little crazy and modifiying on object over and over again. ## Sample Analysis Script Our analysis script is a simple Python script that takes an OSLC Connect downloaded TRS Archive and provides a summary of events and event rates, as well as a basic plot. We encourage administrators to use these tools to understand TRS and their own enterprise better. Our scripts are not supported features of the product, but rather examples to help you explore and build a deeper understanding. ## Example Results So let's look at some example results. Executing the script is relatively simple. python trsAnalysis.py TrsFeed_cm_2025-04-21T17_17_52.zip Textually, it will provide a set of responses * The size of the base members (basic monitoring size) and changes (events over the last 7 days) * A summary of hourly events to see how heavy or steady the change events are occuring * A list of the most often changed artifacts to observe if there is an unnatural number of changes happening on items * And an outline of the total number of differnet types of events (Modification, Creation, and Deletion) In addition, you will have a plot generated that will show the changes over a period of time. For example -\> ![image-20250422-150030.png](https://docs.sodiuswillert.com/__attachments/a_40adabdd76e57fdf57235a3a29be245f14952e0d220b94caa5bb6ee5a4d4c6dc/image-20250422-150030.png?cb=1bb006d47c5f56a6e5813c7793cffe96) Or in more active systems, you may see a shorter duration with more active hourly events. ![image-20250422-150145.png](https://docs.sodiuswillert.com/__attachments/a_ebc4838879d80a165e4213c7d822f4f14b1bb2484443d37acc723d86b1dff129/image-20250422-150145.png?cb=721415666f0142dc44ef016efc2f5e41) And when we looking at TRS feeds for process (projects) we usually see a much calmer and smaller set of changes. Note also that with the process feed, we see a natural rhythm around 1600, which relates to the daily repair event when we publish project changes. ![image-20250422-150819.png](https://docs.sodiuswillert.com/__attachments/a_9f46fd4c145b674975e660b7bbe6304183d58b8222f0fe94d6bdbcde7d84cd19/image-20250422-150819.png?cb=649db968a023c33f867f136fc2825536) ### Sample Python Code Here is the sample Python code to review, tune, and improve. [trsAnalysis.py](https://docs.sodiuswillert.com/__attachments/a_50cb424dd9445281ff08173eb4e5b51f6e146625c901e21d4bff609a471d4157/trsAnalysis.py.md?cb=7d46026e67030d0bf5101b23c0e76236) --- version: "Working version" language: "en" --- # Manually Approving a Consumer in Polarion While the standard flow in Polarion is to Approve the Consumer when you create the Friend from the remote tool, this is not always possible. It is common that a single user is not an admin of both repositories and can't complete the approval. So how does the Polarion Admin approve requests? As a Polarion Admin, you need to go to the Manage OAuth Consumers page. The location of this page is `https:///polarion/oslc/services/oauth/approveKey`, where `` needs to be updated to match your actual Polarion server's URL. ## Checking on your Friend request If your OSLC Connect tool has sent out a Friend request to your ELM Application, there will be a corresponding Consumer under the `Provisional Keys` section: ![image-20220217-071516.png](https://docs.sodiuswillert.com/__attachments/a_1ec5daeec6a58183956e93c72afc40a94744ddab3a68fc97b1cdb3d695d0f8ac/image-20220217-071516.png?cb=af986667b143f61ac793eed30d5fc0bd) ## Approving your new Friend request You can approve this new request by adjusting the `Consumer Name` and selecting clicking the green checkmark in the `Action` column to approve the key. Repeat this process for all required pending Consumers to finalize the Friend connections with your OSLC applications. ## Some checks before moving on... Once all Consumers have been Approved, they should be listed in the Authorized Keys section of this consumer page. ![image-20220217-072109.png](https://docs.sodiuswillert.com/__attachments/a_28e83310a851944e1dd94a2b6cbeedaf0a8db0bea4b45b5251663cadf3dbb5b7/image-20220217-072109.png?cb=1c2fed2a117a46c73656207c9d3d2b9d) --- version: "Working version" language: "en" --- # Basic Friending Rules with OSLC Connect for Jira and IBM ELM When connecting IBM ELM to OSLC Connect to Jira there are many connections that need to be created. The following is a guide on the relationships that need to be established and the basic flow. ## Friending Basics Friending is part the other process of enabling secure interaction between two tools. When creating a Friend, we need to both point to a remote server's rootservices document and approve the Consumer key in the remote applications. These are pairs, the Friend is the source of the request, the Consumer is the recipient that must be authorized. Unfortunately these are not bidirectional relationships so we have many relationships we need to setup. ## Friending from Jira From Jira we need to friend to multiple servers. Below is a table of the Application, rootservices URL, where to approve, and any notes. You will start the friending process in Jira and complete the approval of the consumer in IBM ELM. You find the Friends Page @ {Jira Server}/plugins/servlet/oslc/friends | **Application** | **Rootservices URL** | **Where to Approve** | **Notes** | |---------------------------------|---------------------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | DOORS Next | {IBM URL Base}/rm/rootservices | {IBM URL Base}/jts/admin#action=com.ibm.team.repository.admin.configureOAuth | You might note in the JTS Consumers that this is the DNG Source by editing the label | | Global Configuration Management | {IBM URL Base}/gc/rootservices | {IBM URL Base}/jts/admin#action=com.ibm.team.repository.admin.configureOAuth | You might note in the JTS Consumers that this is the GC Source by editing the label | | Engineering Test Management | {IBM URL Base}/qm/rootservices | {IBM URL Base}/qm/admin#action=com.ibm.team.repository.admin.configureOAuth | | | Engineering Workflow \& RMM | {IBM URL Base}/ccm/rootservices | {IBM URL Base}/ccm/admin#action=com.ibm.team.repository.admin.configureOAuth | | If your organization has multiple application servers (e.g. rm1, rm2, etc) you will need to create friends on each of those as well. ## Friending from IBM ELM Friending from ELM is more complex, with more connections to be made. These can be broken down into application connections and reporting connections. ### Applications Connections Application connections are made from the ELM applications. In all cases the following should be known. Jira Rootservices → {Jira Server}/rest/oslc/1.0/rootservices (also found on the Jira Consumer Page) Jira Consumer Page → {Jira Server}/plugins/servlet/oslc/consumer | **Application** | **Application Friending URL** | **Notes** | |---------------------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | DOORS Next | {IBM URL Base}/rm/admin#action=com.ibm.team.repository.admin.friends | | | Global Configuration Management | {IBM URL Base}/gc/admin#action=com.ibm.team.repository.admin.friends | You should add a Functional User with Read-Access to your Jira Repository. | | Engineering Test Management | {IBM URL Base}/qm/admin#action=com.ibm.team.repository.admin.friends | | | Engineering Workflow \& RMM | {IBM URL Base}/ccm/admin#action=com.ibm.team.repository.admin.friends | If you are using RMM, you should add a Functional User with Read-Access to your Jira Repository. | | Engineering Insights (Optional) | {IBM URL Base}/relm/admin#action=com.ibm.team.repository.admin.friends | You should add a Functional User with Read-Access to your Jira Repository. | If your organization has multiple application servers (e.g. rm1, rm2, etc) you will need to create friends from each of those as well. The need for the Functional User is for some link discovery scenarios where IBM does not provide user credentials. ### Reporting (\& Discovery) Connections For the enhanced capabilities for IBM ELM, there are additional connections that need to be established to complete the behavior. IBM ELM relies on two indexers (LDX \& LQE) to drive some internal functionality. They must be montoring the Jira data sources to provide the desired functionality. To connect the Indexers, you must directly add a Consumer in the Jira Consumer page. Note the Key and Secret since you will need to use those in LDX \& LQE. You can use the same key and secret in all the indexers if desired, but if you want to monitor/control the behaviors, it is often useful to use different keys since network tools (load balancers, reverse proxies, etc) can often filter on the consumer keys. #### Connecting LDX LDX performs the necessary role for link discovery by processing the Jira TRS feed(s). In LDX, a new data source needs to be added. Use the Jira Rootservices ( {Jira Server}/rest/oslc/1.0/rootservices ) to find the CM Resources and add those as a Data Source. (Optional) If you are using test resources (XRay) from Jira, also add the QM Resources as an additional Data Source. #### Connecting LQE LQE performs the necessary role for reporting (Report Builder and Engineering Insights) by processing the Jira TRS feeds. In LQE, a new data sources need to be added. Use the Jira Rootservices ( {Jira Server}/rest/oslc/1.0/rootservices ) to discover the available feeds. Add the Jira Process Resources. This will enable visibility to the Jira Projects in the Reporting Tools. Note, the permissions on who can report on this data are controlled by the LQE Permissions based on these projects. Add the Jira CM Resources. This will enable the access to the data on the individual Jira Issues. (Optional) If you are using test resources (XRay) from Jira, also add the QM Resources as an additional Data Source. If you have issues, please see → [Issues using OSLC Connect with ReportBuilder](https://docs.sodiuswillert.com/oslc-connect/latest/issues-using-oslc-connect-with-reportbuilder.md) --- version: "Working version" language: "en" --- # Bulk Bidirectional Link Deleter In many OSLC systems we have bidirectional links. We can write scripts that can delete on both ends by using the Sodius APIs. Following is an example that deletes both locally and the links in the remote tooling. It serves as an example of what you might be interested in doing. It uses the local link type to determine the remote link and then searches based on the link and URL of the Jira issue. Try it in test mode, and refine the behavior you want. Groovy import com.onresolve.scriptrunner.runner.customisers.WithPlugin; import com.atlassian.plugin.PluginAccessor import com.atlassian.jira.component.ComponentAccessor; import com.atlassian.jira.issue.link.RemoteIssueLinkManager; import com.atlassian.jira.issue.link.RemoteIssueLink; import org.apache.log4j.Logger; import org.apache.log4j.Level; import com.sodius.oslc.core.process.model.LinkType; import com.sodius.oslc.core.process.links.model.DirectedLink; import com.sodius.oslc.core.process.links.requests.AddLink; import com.sodius.oslc.core.process.links.requests.RemoveLink; import org.eclipse.lyo.oslc4j.core.model.Link; import com.sodius.oslc.client.OslcClient; import com.sodius.oslc.client.OslcClients; @WithPlugin("com.sodius.oslc.app.jira") def log = Logger.getLogger("com.onresolve.scriptrunner.runner.ScriptRunnerImpl") def rootUrl = ComponentAccessor.getApplicationProperties().getString('jira.baseurl') // Set the log level. // Test mode disables the creation but runs all the checks log.setLevel(Level.INFO); boolean testMode = true; boolean removebacklinks = true; boolean jazz = true; // Set the local username to be logged as the action performing the work def userName = "bob" // Set the remote user name and password def remoteUserName = "patricia" def remoteUserPassword = "patricia" // Metrics counters int deletedLinks = 0; int issueCount = 0; log.info("Starting Sodius Link Bidirectional Deletion") // Get the local Jira user def user = ComponentAccessor.getUserManager().getUserByName(userName) // Get the remote Client (assuming all links are to the same respository) - note jazz/IBM have different client connections // Updated based on Adaptavist guidance def userCredentials = ComponentAccessor.getComponent(PluginAccessor).getEnabledPlugin("com.sodius.oslc.app.jira").getClassLoader() .loadClass("org.apache.http.auth.UsernamePasswordCredentials") .getConstructor(String, String) .newInstance(remoteUserName, remoteUserPassword) def client = null try { if (jazz) { client = OslcClients.jazzForm( userCredentials ).create(); } else { client = OslcClients.basic( userCredentials ).create(); } } catch (Exception ex) { log.info("Unable to create a client. Exiting." + ex.getMessage() ) return } // Search parameter can be set to '' to get all issues from all projects or add 'AND issuekey = JPG-3' to filter on a specific issue Issues.search('project = AMRPORTLAND AND issuekey = AMRPRT-2').findAll { issue -> log.info "Looking at issue " + issue.getKey() issueCount++; def remoteIssueLinkManager = ComponentAccessor.getComponent(RemoteIssueLinkManager.class) // Iterate over links (OSLC Links are stored as Remote Links tied to tha Application Type com.sodius.oslc.app.jira) for (RemoteIssueLink existingLink in remoteIssueLinkManager.getRemoteIssueLinksForIssue( issue ) ) { // Need to check for the application owner to get all of the OSLC Links // It is assumed that backlinks exist and must be deleted. If using GC, just set removebacklinks to false if ( existingLink.getApplicationType() == "com.sodius.oslc.app.jira" ) { // found a OSLC link, we should consider deleting it log.info ( 'Evaluting ' + issue.getKey() + ' -> ' + existingLink.getUrl() + ' of type ' + existingLink.getRelationship() ) if ( !testMode ) { // Remove the remote link if (removebacklinks) { DirectedLink directedLink = new DirectedLink() def URI backlinkType = getBacklinkType( existingLink.getRelationship() ) if ( backlinkType != null ) { directedLink.setPropertyDefinition( backlinkType ) directedLink.setSource(URI.create( existingLink.getUrl() )) directedLink.setTarget(new Link(URI.create( rootUrl + '/rest/oslc/1.0/cm/issue/' + issue.getKey() ))) try { def removeLinkResponse = new RemoveLink(client, directedLink).call() log.info ('Deleted backlink') } catch (Exception ex) { log.warn("Caught exception ->" + ex.getMessage()) } } else { log.info("No defined backlink for " + existingLink.getRelationship() + " skipping backlink deletion") } } // Remove the local link remoteIssueLinkManager.removeRemoteIssueLink( existingLink.getId(), user ) log.info('Deleted local link') } else { log.info( 'Test Mode (skipped deletion)') } deletedLinks++; } } } log.info("Reviewed " + issueCount + " issues") if ( testMode ) { log.info("[TESTMODE] Planned to delete " + deletedLinks + " links ") } else { log.info("Deleted " + deletedLinks + " links ") } def URI getBacklinkType(String relationship) { switch (relationship) { case "related change request": return LinkType.RELATED_CHANGE_REQUEST.getPropertyDefinition() case "implements requirement": return LinkType.IMPLEMENTED_BY.getPropertyDefinition() case "tracks requirement": return LinkType.TRACKED_BY.getPropertyDefinition() case "affects requirement": return LinkType.AFFECTED_BY.getPropertyDefinition() case "affected by defect": return LinkType.AFFECTS_PLAN_ITEM.getPropertyDefinition() case "affects plan item": return LinkType.AFFECTED_BY_DEFECT.getPropertyDefinition() case "contributes to": return LinkType.TRACKS_WORK_ITEM.getPropertyDefinition() case "tracks": return LinkType.TRACKED_WORK_ITEM.getPropertyDefinition() default: return null } } For a simple, local only, deletion see [Bulk OSLC Local Link Deletion](https://docs.sodiuswillert.com/oslc-connect/latest/bulk-oslc-local-link-deletion.md) --- version: "Working version" language: "en" --- # Bulk OSLC Local Link Deletion Occasionally, we must delete all OSLC links locally in our Jira repository. The following script allows us to do this quickly on a project or issue level. This script only operates locally in Jira. To delete remote links, see the remote link deletion script. This script is most useful for projects connecting to IBM ELM projects where no backlinks are stored in the other repository. Groovy import com.atlassian.jira.component.ComponentAccessor; import com.atlassian.jira.issue.link.RemoteIssueLinkManager; import com.atlassian.jira.issue.link.RemoteIssueLink; import org.apache.log4j.Level; // Set the log level. log.setLevel(Level.INFO); // Test mode disables the delete but runs all the checks boolean testMode = true; // Set the local username to be logged as the action performing the work def userName = "bob" // Metrics counters int deletedLinks = 0; int issueCount = 0; log.info("Starting OSLC Link Local Deletion") // Get the local Jira user def user = ComponentAccessor.getUserManager().getUserByName(userName) // Search parameter can be set to '' to get all issues from all projects or add 'AND issuekey = JPG-3' to filter on a specific issue Issues.search('project = AMRPORTLAND AND issuekey = AMRPRT-1').findAll { issue -> log.info "Looking at issue " + issue.getKey() issueCount++; def remoteIssueLinkManager = ComponentAccessor.getComponent(RemoteIssueLinkManager.class) // Iterate over links (OSLC Links are stored as Remote Links tied to tha Application Type com.sodius.oslc.app.jira) for (RemoteIssueLink existingLink in remoteIssueLinkManager.getRemoteIssueLinksForIssue( issue ) ) { // Need to check for the application owner to get all of the OSLC Links // It is up to the user to ensure that backlinks do not exist if ( existingLink.getApplicationType() == "com.sodius.oslc.app.jira" ) { // found a OSLC link, we should consider deleting it log.info ( 'Evaluting ' + issue.getKey() + ' -> ' + existingLink.getUrl() + ' of type ' + existingLink.getRelationship() ) if ( !testMode ) { // Remove the local link remoteIssueLinkManager.removeRemoteIssueLink( existingLink.getId(), user ) log.info('Deleted remote link id:' + existingLink.getId() + ' -> ' + existingLink.getUrl() + ' of type ' + existingLink.getRelationship() ) } else { log.info( 'Test Mode (skipped deletion)') } deletedLinks++; } } } log.info("Reviewed " + issueCount + " issues") if ( testMode ) { log.info("[TESTMODE] Planned to delete " + deletedLinks + " links ") } else { log.info("Deleted " + deletedLinks + " links ") } --- version: "Working version" language: "en" --- # Can't add datasources from Rootservices? Setting the protocol for outbound ELM requests OSLC connections depend on secure and consistent network connections. In many corporate IT systems, the standard minimum is changing to TLS 1.2. In most cases, our network connections will negotiate the highest supported TLS protocol. However, we have observed in some ELM deployments the outbound requests from ELM not automatically supporting TLS 1.2 for outbound requests and preventing connections to external applications. There are two scenarios where we observe the behaviors of TLS mismatch. 1. When attempting to friend between an application and an OSLC Connect solution, we are notified of a protocol mismatch (either in the UI or in the logs). 2. When attempting to connect a TRS feed from LQE or LDX to OSLC Connect, we observe a "No data sources were found" with a valid rootservices URL. It will look similar to the following: ![deb93b19-5ebb-410b-9e9d-f5dba363616e.png](https://docs.sodiuswillert.com/__attachments/a_64766d1d1f1c8bfbad5b4fa76bc9f7ea322b7be3604fe9f42e98bd66ca965545/deb93b19-5ebb-410b-9e9d-f5dba363616e.png?cb=fc2de68b95e56e24c178589fbd096232) Once we have ruled out network connectivity issues (DNS, Firewall issues, bad rootservices URL), we have identified the protocol mismatch error. We can suggest the problem is that outbound requests for ELM are not supporting TLS 1.2. We can validate this suggestion with the check of the Jira endpoint with a simple curl check as follows: curl -IvL --tlsv1.2 https://myjiraserver/rest/oslc/1.0/rootservices To ensure ELM outbound requests support TLS 1.2, you should take the following steps for each application server with connection issues. To perform the required actions demands both root access to the ELM application server(s) and performing a server restart. Please work with your ELM administrator to execute the following steps: 1. Navigate to your JazzTeamServer installation directory\\server\\liberty\\servers\\clm 2. Create or edit the file: jvm.options 3. Add the following line to this file: -Dcom.ibm.team.repository.transport.client.protocol=TLSv1.2 4. Save the file and restart your ELM service. 5. Once everything is back up, verify that you are now able to make friend and TRS connections. --- version: "Working version" language: "en" --- # Checking the Contents of LDX When users are using Global Configurations and have questions about links not being visible in applications, it can be helpful to explore the link index directly to identify the source of the issue. Incorrect data is the most common issue with missing link discovery. The second most likely cause is a not updated index (LDX). A few simple queries allow users (and Administrators) to answer some key questions. These queries can all be run on the Query page of LDX (https://myldxserver/ldx/web/query#sparql). ![image-20240306-161609.png](https://docs.sodiuswillert.com/__attachments/a_090891fa93571b07696430a468508cb8889a35b00cd2d217f06ba5d12f8fcf6b/image-20240306-161609.png?cb=f7cf0f027225c1c564f8bb7dc85f6bc0) Following are some critical questions to address why link discovery is not working as expected. ## Is my issue in the index? The following query gives us details if issue 'AMRPRT-1' (`https://phoenix-jira.sodiuswillert.cloud/rest/oslc/1.0/cm/issue/AMRPRT-1`) is in the index and the stored set of information. The result will let us know if this artifact is known to LDX. PREFIX oslc_cm: PREFIX oslc: PREFIX rdf: SELECT * WHERE { VALUES ?resourceURL { } { ?resourceURL rdf:type ; ?p ?o; } } The result (if it is indexed) should look something like the following: ![image-20240306-161835.png](https://docs.sodiuswillert.com/__attachments/a_7d7f37c93d3f60e07c11fe16ea56cbfeeb43f52091beff9196dc9a5b68401e96/image-20240306-161835.png?cb=0797bb127e539f7362ec6c6faa444dc6) It should be a collection of links and targets pointing from the resource URL in Jira. Note, LDX drops non-link related information, so if you run this in LQE you will get more information. *If there is no data this means that your issue is not being read by LDX and you must check the Data Source for Jira or whether all projects are being exposed from Jira.* ## What Jira Release are my links targeting? It is essential to have an issue and have it indexed. However, we must also see what Jira release these links are targeting. We can do this with another query. PREFIX oslc_cm: PREFIX oslc_cm: PREFIX oslc: PREFIX rtc_cm: PREFIX oslc_cm: PREFIX oslc: PREFIX rdf: PREFIX rtc_cm: SELECT ?resourceURL ?relation ?target ?context WHERE { VALUES ?resourceURL { } { ?source rdf:subject ?resourceURL; rdf:object ?target ; rdf:predicate ?relation } OPTIONAL { ?source rtc_cm:deliverable ?context . } } The results of this query show details about both the link and the Jira version. ![image-20240306-162708.png](https://docs.sodiuswillert.com/__attachments/a_7be024ff0cd090ef8ebbc15735b785cb95cf0e94229ef9d52f0fc98fa98cfe2a/image-20240306-162708.png?cb=bfbf284bcffa79f6aee587afc8aa7526) In this case, we see that the Jira links are present in the Jira Release ''. This would mean that viewing these resources in the GC that includes this Jira Release would have these links discovered. *If your link does not have a Jira Release/Context, this would target a missing Fixed Version or Affect Version filed in Jira.* ## What Global Configuration is using my Jira Release? We can use the information above to observe what GCs are using that Jira release. In this case, we are looking at 'Version 1' (`https://phoenix-jira.sodiuswillert.cloud/rest/oslc/1.0/cm/version/10101`) PREFIX oslc_cm: PREFIX oslc_cm: PREFIX oslc: PREFIX rtc_cm: PREFIX dcterms: PREFIX rdf: SELECT DISTINCT ?title ?configuration ?jiraDeliverable WHERE { VALUES ?jiraDeliverable { } VALUES ?streamType { } { ?configuration a ; rtc_cm:deliverable ?jiraDeliverable; rtc_cm:deliverable ?deliverable ; dcterms:title ?title ; rdf:type ?streamType; } } ORDER BY ?configuration LIMIT 100 With results like the following that show which Global Configurations, you would expect this Jira item to appear. ![image-20240306-163723.png](https://docs.sodiuswillert.com/__attachments/a_a01c761d31a38c52111856409bc93ef9d03f2aa0eff36caf5b46675b7b2bdb7b/image-20240306-163723.png?cb=559d682a2bf1be4af8e820d76e825e03) *If your expected GC is not listed, it means your Jira Release is not linked in the GC Configuration.* ## How do I check the data from Jira? If you are wondering about the data that LDX is reading, you can always get it directly from Jira. Go to Manage Apps -\> OSLC Connect → Issue Shapes ( Select the default scheme. And select the "Show Resource Shape." ![image-20240306-164529.png](https://docs.sodiuswillert.com/__attachments/a_cf06756a507f08cf05c4c1e0500126959be0bdf5a7ccdbbab6c488b3564473b5/image-20240306-164529.png?cb=13bd9551356be19ead0f166704ba8ea4) Type in your Jira Issue Key, and download resource the XML form. ![image-20240306-164610.png](https://docs.sodiuswillert.com/__attachments/a_ac6e549f88002e0cad07a3c34495a48afff66e07ac2d3f4e0356cb3f635db286/image-20240306-164610.png?cb=2c1459c4d1712aac9e224e7e25725b37) You can view this XML file and see what LDX is reading, including the raw link data and the deliverable context for the link. ![image-20240306-164728.png](https://docs.sodiuswillert.com/__attachments/a_cd7dbde05a01ca40e99fb05a4afb7df88729477ab146da063c13d3505799b307/image-20240306-164728.png?cb=706b9a28ffe7cfee3be1c53999159f98) If the data is different from LDX, that means LDX isn't up to date, and an Administrator should be notified to check the Jira Data Source. --- version: "Working version" language: "en" --- # Content Security Policy Recommendations with OSLC Content Security Policy is a useful tool to shape the security of any of your web applications. It is common in enterprise IT standards to enforce policies to limit the embedded content from remote sites. However, with OSLC, we intend to embed content from remote sites. So how do we manage the critical collaboration as well as security policies? For many organizations, this is the intersection of their OSLC needs and their existing CSP directives. ## What is Content Security Policy (CSP)? Content Security Policy is intended to mitigate injection attacks that look like trusted sources to the end-user. Security teams can define a policy that is enacted by a set of directives implemented in the Content-Security-Policy header of web traffic. These directives () are enforced at the browser level and make sure users are shielded from undesired behavior and content from websites. ## Where is CSP Enacted? The CSP headers can be injected from multiple sources within an enterprise. This includes the web application directly, the web-server, and/or a proxy/load-balancer. Your enterprise architecture will be critical for understanding and managing your OSLC deployment. This includes your application servers, the proxies, the networks, and the unique domains. It is often valuable to draw a simple diagram to be able to explain the features and nodes. It is almost always feasible with each node and proxy/passthru that we can add or remove content to the network traffic, including security headers. How security headers are introduced depends on the technology. For example, if you happened to have a proxy in front of your OSLC application, it has the opportunity to modify the traffic it observes. If you are using HA Proxy, it is a simple instruction to rewrite content to include a header. The following would ensure that all http responses include a specific CSP directive. http-response set-header Content-Security-Policy "frame-ancestors 'self'" This simple statement can have a large impact on the way your enterprise behaves. It is enacting a specific policy on all traffic to control where content can be embedded. This is both powerful and challenging to manage. Following we will offer tools to understand CSP and its interaction with OSLC. ## How does OSLC interact with CSP? OSLC interaction with CSP is relatively tightly constrained. This because OSLC is focused on embedding content rather than embedding scripts. This means if the content is blocked in the browser, it is likely one of the following sources. ### frame-src A frame-src () directive will identify the valid sources that could be embedded into a frame/iframe. This allows a page to identify where other content can come from. The most common default CSP with this directive is: Content-Security-Policy: frame-src 'self'; This directive would instruct that for all iframe sources requested; they must all come from the same site (URL scheme and port). Let's consider an example. If this policy is set on a proxy in front of your Jira solution, it would be unable to embed content from any of its OSLC Friends. There would be no restriction, however, on the consumers embedding content from this Jira instance with this policy. ### frame-ancestors A frame-ancestors () directive will identify what sites can embed your content. This allows a page to identify how, or more specifically, where, it can be used. The most common default CSP with this directive is: Content-Security-Policy: frame-ancestors 'self'; This directive would instruct that only the current site could be used for all usages of content from this source. Again, when using an example. If this policy is set on a proxy in front of your Jira solution, it would prevent any of its OSLC Consumers from embedding the content from Jira. There would be no restriction on Jira from embedding content from its Friends with this policy. ### Policies CSP Directives can be combined to create the entire policy. Each directive is separated by a ';' and has space-delimited lists of values. For example, the following CSP: Content-Security-Policy: frame-ancestors 'self'; frame-src 'self'; Would prevent any other site from using content from this page or using content from another site. It is very secure. However, if your IBM ELM environment is on and your Jira is on , then there will be no embedding of content between the applications. Your OSLC Enterprise will be broken. ## Recommendation Policy Pattern with OSLC We have two possible suggestions for CSP Policies. Option 1 is the simplest. It is perfectly reasonable and entirely secure not to have any content security policy. The exclusion of CSP directives on your OSLC solutions is a path. Option 2 is slightly more complicated but will have stronger approval from your IT Security team. We recommend you use both frame-src and frame-ancestors to provide a robust limit of external interaction and smooth collaboration of your OSLC tools. In OSLC, we describe the set of Friends as the ones that we want to embed their content. This we can align to a frame-src directive. frame-src https://myfriend1.com https://myfriend2.com:9443 'self'; In OSLC, we describe the set of Consumers as the ones that we are allowing to use our content. This we can align to a frame-ancestors directive. frame-ancestors https://myconsumer1.com https://myconsumer2.com:9443 'self'; It is often the case that the Friends and Consumer list is the same because we usually do OSLC bi-directionally. However, there are some cases where a reporting tool may only be a consumer, so we should keep this consumer/friend distinction in mind. For each of these directives, the technology solution you implement will vary. We recommend reviewing the details both with the IT Security team and the Administrator of your web application or proxy. These suggested values only enable the required OSLC interaction of a particular application. If there are additional rules or exceptions, it is up to your security team to incorporate these rules. --- version: "Working version" language: "en" --- # Debugging errors using Jazz / CLM / ELM log files Depending on the situation you're analyzing, you may enable different loggers. Here are some recommendations we have found valuable over the past years doing support for OSLC Connect for Jira. ## Prepare your logs with some specific notes When doing debug sessions, it's always valuable to easily identify what actions were undertaken when a specific log message appears. The start of the session deserves a specific notice, as would any action that one would perform, e.g. the last click before a given problem appears or the modification of a specific configuration key. This will help review the logs immediately after the session, but also will help with retaining a certain level of understanding weeks on months later. Since IBM does not offer the same level of features as does Atlassian in their Jira product, we have to resort to using administrator tricks here! Our suggestion for this is to: * identify which files you wish to supervise * log into these files with the following script (choose one that matches your system) Linux #!/bin/sh for i in "${@:2}" do echo -ne "\n\n\n**** ${1}\n\n" >> ${i} # mark the nth log file done exit Create the `marklogs.sh` file inside the logs folder (typically `/server/liberty/servers/clm/logs` then make it executable (using `chmod u+x marklogs.sh`). You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments: ./marklogs.sh "Starting the OSLC debug session" ldx.log ldx-internalSso.log Windows (Powershell) $log_mark=$args[0]; for ($i = 1; $i -lt $args.count; $i++) { $logfile = $args[$i]; Add-Content "$logfile" "`n`n`n*** $log_mark`n`n"; } Create the `marklogs.ps1` file inside the logs folder (typically `\server\liberty\servers\clm\logs`. You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments: .\marklogs.ps1 "Starting the OSLC debug session" ldx.log ldx-internalSso.log Windows (Batch) @echo off setlocal enabledelayedexpansion set argCount=0 for %%x in (%*) do ( set /A argCount+=1 set "argVec[!argCount!]=%%~x" ) for /L %%i in (2,1,%argCount%) do ( (echo:& echo:& echo:& (echo *** %~1)& echo:& echo:)>>"!argVec[%%i]!"" ) Create the `marklogs.bat` file inside the logs folder (typically `\server\liberty\servers\clm\logs`. You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments: marklogs.bat "Starting the OSLC debug session" ldx.log ldx-internalSso.log The result will look like this: 2021-11-05 04:57:51,903 [Default Executor-thread-678099 @@ 04:57 patricia /ccm/proxy] WARN net.jazz.ajax.service/ProxyOperation - The target https://ulm-jira-7.sodius.cloud:4430/rest/oslc/1.0/rootservices is not local and not registered as a friend *** Starting the OSLC debug session ## Decide on what to review ### Review incoming requests to ELM You should do that if your OSLC Connect application is experiencing problems interacting with ELM. Incoming requests are visible in the HTTP access log. This access log is provided by Liberty and can be enabled [as described at Jazz.net](https://www.ibm.com/docs/en/was-liberty/core?topic=SSD28V_liberty/com.ibm.websphere.wlp.doc/ae/rwlp_http_accesslogs.html). Concretely, we recommend that you enable the access log on the targeted endpoint. A good value for the access log format would typically give out the following configuration block to update in the default server.xml: To better understand the log format and customize it to your needs, you may want to [review this article](https://www.ibm.com/docs/en/was-liberty/core?topic=SSD28V_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_feature_servlet-3.0.html). For an advanced access log format, you can expand this section. HTTP headers retained in the following suggested example were taken from [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). logFormat="'%h' '%u' '%t' '%D' '%r' '%s' '%B' '%m' '%U' '%q' '%a' '%A' '%C' '%{Referer}i' '%{User-Agent}i' '%{Cookie}i' '%{Authorization}o' '%{Set-Cookie}i' '%{oslc_config.context}i' '%{OSLC-Core-Version}i' '%{Content-Length}i' '%{Accept}i' '%{Content-Type}i' '%{If-Match}i' '%{If-Modified-Since}i' '%{X-If-Modified-Since-XSD}i' '%{Forwarded}i' '%{X-Forwarded-For}i' '%{Location}o' '%{Content-Location}o' '%{Content-Disposition}o' '%{eTag}o' '%{x-com-sodius-logout-url}o' '%{x-com-sodius-logout-method}o' '%{X-com-sodius-oauth-redirect-location}o' '%{X-com-ibm-team-repository-web-auth-msg}o' '%{X-Sodius-Resource}o' '%{WWW-Authenticate}o' '%{Last-Modified}o' '%{Access-Control-Allow-Origin}o' '%{Vary}o' '%{Origin}o' '%{X-Frame-Options}o' '%{Content-Security-Policy}o'" Which gives out the following log: '10.100.99.5' '-' '[16/Jun/2020:07:41:36 +0200]' '628158' 'GET /secollab/web/clm/review/67082340-c545-4c86-acd7-7cd1ea2fda08/finalize?oslc_config.context=https:%2F%2Fclm-605.sodius.cloud:9443%2Fsecollab%2Fclm%2Fservices%2Fconfig%2Fstream%2F213e8151-5010-4722-a996-d1f64df4944e HTTP/1.1' '307' '0' 'GET' '/secollab/web/clm/review/67082340-c545-4c86-acd7-7cd1ea2fda08/finalize' '?oslc_config.context=https:%2F%2Fclm-605.sodius.cloud:9443%2Fsecollab%2Fclm%2Fservices%2Fconfig%2Fstream%2F213e8151-5010-4722-a996-d1f64df4944e' '10.100.99.5' '10.100.2.102' 'JSESSIONID:0000Voxgdm9kVpWRykb_1CGRSVN:5c53c125-1133-4b4d-ba65-e9e16fe6471e LtpaToken2:fjhBhxSwdPdirZzMIvZrff57j4FlS+lk/AtmCinLpdV/MER1cRHFvfAU2yrQF/YbxHEEZOKBDrrgN2BDEuOMkgVJBIjBOmM7pnioeXweRou7h9RnMMYdeCy2ePd02Ix8n8i2pUZyrfwd55apC6rQLsWIZFWjJN9lpRZrrIq5Ok3vsKsIzfv9idGIJpFhOUx6jTQuqfVOpYX4wpJ+jUuHYTDu6slRDe9pQBlw7OT5qWn8TW59WeKDVXrtFbWRo7POvNEfH1uEd4Ec3RBc5bxihsWPnKPL3eGGmLuFsaxatkMNgJkCKd5HUwAgz3YGRXeb' '-' 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:77.0) Gecko/20100101 Firefox/77.0' 'JSESSIONID=0000Voxgdm9kVpWRykb_1CGRSVN:5c53c125-1133-4b4d-ba65-e9e16fe6471e; LtpaToken2=fjhBhxSwdPdirZzMIvZrff57j4FlS+lk/AtmCinLpdV/MER1cRHFvfAU2yrQF/YbxHEEZOKBDrrgN2BDEuOMkgVJBIjBOmM7pnioeXweRou7h9RnMMYdeCy2ePd02Ix8n8i2pUZyrfwd55apC6rQLsWIZFWjJN9lpRZrrIq5Ok3vsKsIzfv9idGIJpFhOUx6jTQuqfVOpYX4wpJ+jUuHYTDu6slRDe9pQBlw7OT5qWn8TW59WeKDVXrtFbWRo7POvNEfH1uEd4Ec3RBc5bxihsWPnKPL3eGGmLuFsaxatkMNgJkCKd5HUwAgz3YGRXeb' '-' '-' '-' '-' 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8' '-' '-' '-' '-' '-' '-' 'https://clm-605.sodius.cloud:9443/ccm/oauth-authorize?oauth_token=fdfb3353c8ae4387880b5e63aa6095f4' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' Log parameters used in this recommandation are: * %h Remote host * %u Remote user according to the WebSphere Application Server specific $WSRU header * %t NCSA format of the start time of the request * %D The elapsed time of the request - millisecond accuracy, microsecond precision * %r First line of the request * %s Status code of the response * %B Response size in bytes excluding headers. 0 is printed instead of - if no value is found. * %m Request method * %U URL Path, not including the query string * %q Output the query string with any password escaped * %a Remote IP address * %A Local IP address * %C Cookie Retained HTTP request headers are: * Referer * User-Agent * Authorization * Cookie * Set-Cookie * oslc_config.context * OSLC-Core-Version * Content-Length * Accept * Content-Type * If-MatchIf-Modified-Since * X-If-Modified-Since-XSD * Forwarded * X-Forwarded-For Retained HTTP response headers are: * Location * Content-Location * Content-Disposition * eTag * x-com-sodius-logout-url * x-com-sodius-logout-method * X-com-sodius-oauth-redirect-location * X-com-ibm-team-repository-web-auth-msg * X-Sodius-Resource * WWW-Authenticate * Last-Modified * Access-Control-Allow-Origin * Vary * Origin * X-Frame-Options * Content-Security-Policy * Downstream-Auth To make use of the output in Excel: * Copy the below header line to the first line of an Excel Sheet 'Remote host' 'Remote user' 'Request start time' 'Request log time' 'Request duration' 'Request 1st line' 'Status' 'Response size' 'Method' 'URL' 'Query string' 'Cross Component Tracing (XCT) Context ID' 'Remote IP addr' 'Local IP addr' 'Cookie' 'i_Referer' 'i_User-Agent' 'i_Authorization' 'i_Cookie' 'i_Set-Cookie' 'i_oslc_config.context' 'i_OSLC-Core-Version' 'i_Content-Length' 'i_Accept' 'i_Content-Type' 'i_If-Match' 'i_If-Modified-Since' 'i_X-If-Modified-Since-XSD' 'i_Forwarded' 'i_X-Forwarded-For' 'o_Location' 'o_Content-Location' 'o_Content-Disposition' 'o_eTag' 'o_x-com-sodius-logout-url' 'o_x-com-sodius-logout-method' 'o_X-com-sodius-oauth-redirect-location' 'o_X-com-ibm-team-repository-web-auth-msg' 'o_X-Sodius-Resource' 'o_WWW-Authenticate' 'o_Last-Modified' 'o_Access-Control-Allow-Origin' 'o_Vary' 'o_Origin' 'o_X-Frame-Options' 'o_Content-Security-Policy' * Copy the lines you want to investigate to the 2nd+ line of the Excel Sheet *if the copied header or lines are not automatically expanded to columns* 1. Select column Accept 2. In the "Data" banner, click the button called "Text to Column" 3. Choose "delimited", then Next ### Review outgoing requests sent by ELM, or the ELM processing Depending on the applications installed, there can be 2 ways to set up additional application logs #### For RM... Navigate to `https://server:9443/rm/admin#action=com.ibm.rdm.fronting.server.web.logging`. Click on **Configure Loggers**, then find the logger you want to change and click on the log level you want to set. #### For any ELM application... 1. On Jazz server, edit the file at `\server\conf\\log4j.properties` 2. Update the content of the file (see examples below) and save it 3. Reload the logging settings: 1. For all apps but LQE/LDX, navigate in a browser to: `https://server:9443//admin?internal=true#action=com.ibm.team.repository.admin.reloadLoggingSettings` 2. For LQE/LDX, go to `https://server:9443/lqe/web/admin/data-sources` → Advanced Properties 4. Click the **Reload Log Settings** button 5. Download the log files as explained below #### Reviewing outgoing requests To debug ELM outgoing requests, add the following lines in Log4j configuration: log4j.logger.org.apache.http=DEBUG #### Reviewing ELM processing * To debug link discovery in DNG, add the following lines to RM's Log4J configuration: log4j.logger.com.ibm.rdm.fronting.server.services.discoveredlinks=DEBUG log4j.logger.com.ibm.rdm.fronting.server.services.linkindexprovider=DEBUG log4j.logger.com.ibm.team.links=DEBUG * To debug LQE HTTP requests to TRS feeds, add the following line in Log4j configuration: log4j.logger.com.ibm.team.integration.lqe.lib.trsparser.ITRS=TRACE #### Where to review You will always review the file corresponding to the application where you have enabled specific logs. The below table lists most of them. | **Log File** | **Name (v6)** | **Name (v7)** | |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ccm.log | [RTC](https://www.ibm.com/support/knowledgecenter/en/SSYMRC_6.0.6.1/com.ibm.team.concert.nav.doc/topics/c_node_product_rtc.html) Rational Team Concert | [EWM](https://www.ibm.com/support/knowledgecenter/en/SSYMRC_7.0.0/com.ibm.team.concert.nav.doc/topics/c_node_product_rtc.html) Engineering Workflow Management | | rm.log | [++DNG++](https://www.ibm.com/support/knowledgecenter/en/SSYMRC_6.0.6.1/com.ibm.rational.rrm.help.doc/topics/c_rm_intro.html) Rational DOORS Next Generation | [DOORS Next](https://www.ibm.com/support/knowledgecenter/en/SSYMRC_7.0.0/com.ibm.rational.rrm.help.doc/topics/c_rm_intro.html) Engineering Requirements Management DOORS Next | | qm.log | [RQM](https://www.ibm.com/support/knowledgecenter/en/SSYMRC_6.0.6.1/com.ibm.rational.test.qm.doc/topics/c_qm_top.html) Rational Quality Manager | [ETM](https://www.ibm.com/support/knowledgecenter/en/SSYMRC_7.0.0/com.ibm.rational.test.qm.doc/topics/c_qm_top.html) Engineering Test Management | | gc.log | GCM Global Configuration Manager | GCM Global Configuration Manager | | ldx.log | LDX Link Indexer | LDX Link Indexer | | lqe.log | LQE Lifecycle Query Engine | LQE Lifecycle Query Engine | | relm.log | RELM Rational Engineering Lifecycle Management | EI Engineering Insight | | rs.log | RS Report Builder | RS Report Builder | ## Finishing the debug session ### Restore your system's previous logging features You definitely want to mark your logs using the `marklogs.sh` script, e.g. ./marklogs.sh "Completed OSLC debug session" ldx.log ldx-internalSso.log Then to avoid flooding your system with logs, you also want to undo the changes you have made during the debug session. This can be done by commenting out any line added in the log4j.properties files, prefixing them with a `#`. ### Retrieving Jazz' server logs #### From the RM admin page Navigate to `https://server:9443/rm/admin#action=com.ibm.rdm.fronting.server.web.logging`. From this page, you can either download or display in the browser **any log file**from the Jazz server. #### From the Jazz server Open the following file to see the log entries: `/server/liberty/servers/clm/logs/.log` There may be a number of log files ex. rm.log, rm.log1, rm.log2 etc. because when a log file becomes full a new one is created. We suggest attaching the log file(s) to a Jira ticket on our [customer support portal](https://sodius.atlassian.net/servicedesk/customer/portal/39) if you think these provide insight into the problem you have identified, or if they were requested. --- version: "Working version" language: "en" --- # Debugging errors using Jira logs Depending on the situation you're analyzing, you may enable different loggers. Here are some recommendations we have found valuable over the past years doing support for OSLC Connect for Jira. ## Prepare your logs with some specific notes Jira lets you insert a marker in the logs, as well as force a rollover of the log files. * The former helps you find when exactly you started a session. You can also mark an optional comment anytime you start a specific test, so that there is no ambiguity in your log as to what you have achieved in the debug session. With those additional markers, the log will tell you all you need to know. Also note that those markers may very well provide context regarding what will happen, as well as what just happened. You should use that (great) feature extensively in debug sessions. * The latter helps with getting small files that are easier to share at the end of the debug session. In order to do this, you should go to the Mark Logs container, and mark them as suggested below, then click Mark. ![image-20210211-225341.png](https://docs.sodiuswillert.com/__attachments/a_3bb3b99650cce401cb3ae8ccef40e184d91ac724fc20ea351d16ecbb43e0f28b/image-20210211-225341.png?cb=3844a69f4983e5cccd2402b1adfc4a1b) ## Decide on what to review ### Review incoming requests to Jira You should do that if a remote application is experiencing problems interacting with Jira. Incoming requests are visible in the HTTP access log. SodiusWillert Support may ask you to activate these Jira logging: * HTTP Access Log: this contains requests coming from external tools, along with the time of the request and status of the response * HTTP Dump Log: this contains very detailed requests received by Jira, along with the very detailed responses that were prepared and sent by Jira ![CleanShot 2020-05-13 at 15.39.09.png](https://docs.sodiuswillert.com/__attachments/a_bd85b72fb5dfd0992effde79a34bf5dfaeca7585c318c2845e65171d882a52e5/CleanShot%202020-05-13%20at%2015.39.09.png?cb=aeed316d48373f68b6e9066aca50b55c) ![A CleanShot 2020-05-13 at 15.55.50.png](https://docs.sodiuswillert.com/__attachments/a_253b4bd41161de76a961c158216048c48e4221170f29c9d15416f722680f7b1c/A%20CleanShot%202020-05-13%20at%2015.55.50.png?cb=caf36f08565a017def7b62c8fb56bdc9) ### Review outgoing requests sent by Jira and OSLC Connect for Jira The Jira application log will contain everything that is logged by Jira itself, based on what is configured in the **Default loggers**section: ![image-20210211-230441.png](https://docs.sodiuswillert.com/__attachments/a_9eede406fd8de1fc14a6cfa496109ce95f89bbd3cd7ffb6ea16968006f18b4ed/image-20210211-230441.png?cb=27fab17183ceeb70a30efef0b408bb38) This allows us to configure additional logging. The additional logging is based on a source code package that you want to enable logging for. For example, if you want to see the details of the requests sent by Jira, and the responses Jira gets from external OSLC tools, you will want to configure the following packages with a `DEBUG` log level: * `org.apache.http`, to review the details of every request initiated by Jira * `com.sodius.oslc.server.services`, to review the details of the OAuth 1.0a dance provided by ## Finishing the debug session ### Restore your system's previous logging features Upon wrapping up your debug session, you want to make sure all the additional logs you have enabled have been disabled: * If you were reviewing incoming requests, you will want to disable the HTTP Access and HTTP Dump logs * If you were reviewing outgoing requests, you will also want to deactivate the additional default loggers by either restoring the original logging level to an already logged package, or disabling the logging of an added by package by turning it `OFF`. ### Retrieving Jira logs You should create a support .zip file from your Administration page as shown below. ![CleanShot 2020-07-03 at 15.15.02.png](https://docs.sodiuswillert.com/__attachments/a_a1a7a6e20580892bf7c455c35f205a6da3dab3e8249b927f0c882340a986e8fa/CleanShot%202020-07-03%20at%2015.15.02.png?cb=4241310eadcfdd33444a2320500bf411) ![CleanShot 2020-07-03 at 15.17.17.png](https://docs.sodiuswillert.com/__attachments/a_1e42617b590aa79613eaa9dba69333e73764e96d35709650b2a8cf0241125bc1/CleanShot%202020-07-03%20at%2015.17.17.png?cb=b8b0c5026b2f956f0a46b46cdbb0bb53) You can then click the `Create zip` button to generate the zip file which, once ready, you will be able to download and unzip on your computer. Below are the log files that you need to search for (and into): * **atlassian-jira.log** , for Jira application logs and Jira outgoing requests, including the logs from the additional packages enabled above, such as `org.apache.http` or `com.sodius.oslc.server.services` * **atlassian-jira-http-access.log**, for simple Jira incoming requests * **atlassian-jira-http-dump.log**, for detailed Jira incoming requests There may be a number of similar log files e.g. atlassian-jira.log, atlassian-jira.log2, etc. because when we mark the logs at the beginning with the log rollover, as well as when a log file becomes full, a new one is created. If you have only asked for a log rollover once at the beginning of your debug session, then your whole session will be in the non-numbered files. Within these log files, all events are time stamped. So either you have noted roughly when the error occurred or else recreated the error just before looking at the log files. We suggest attaching the log file(s) to a Jira ticket on our [customer support portal](https://sodius.atlassian.net/servicedesk/customer/portal/39). --- version: "Working version" language: "en" --- # Debugging errors using Polarion log files Depending on the situation you're analyzing, you may enable different loggers. Here are some recommendations we have found valuable over the past years doing support for OSLC Connect for Jira. ## Prepare your logs with some specific notes When doing debug sessions, it's always valuable to easily identify what actions were undertaken when a specific log message appears. The start of the session deserves a specific notice, as would any action that one would perform, e.g. the last click before a given problem appears or the modification of a specific configuration key. This will help review the logs immediately after the session, but also will help with retaining a certain level of understanding weeks on months later. Since Siemens does not offer the same level of features as does Atlassian in their Jira product, we have to resort to using administrator tricks here! Our suggestion for this is to: * identify which files you wish to supervise * log into these files with the following script Linux #!/bin/sh for i in "${@:2}" do echo -ne "\n\n\n**** ${1}\n\n" >> ${i} # mark the nth log file done exit Create the `marklogs.sh` file inside the logs folder (typically `/data/logs` then make it executable (using `chmod u+x marklogs.sh`). You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments: ./marklogs.sh "Starting the OSLC debug session" ldx.log ldx-internalSso.log Windows (Powershell) $log_mark=$args[0]; for ($i = 1; $i -lt $args.count; $i++) { $logfile = $args[$i]; Add-Content "$logfile" "`n`n`n*** $log_mark`n`n"; } Create the `marklogs.ps1` file inside the logs folder (typically `/data/logs`. You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments: ./marklogs.ps1 "Starting the OSLC debug session" main/log4j-20211018-1137-19.log main/log4j-oslc-20211028-1235-14.log Windows (Batch) @echo off setlocal enabledelayedexpansion set argCount=0 for %%x in (%*) do ( set /A argCount+=1 set "argVec[!argCount!]=%%~x" ) for /L %%i in (2,1,%argCount%) do ( (echo:& echo:& echo:& (echo *** %~1)& echo:& echo:)>>"!argVec[%%i]!" ) Create the `marklogs.bat` file inside the logs folder (typically `/data/logs`. You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments: ./marklogs.bat "Starting the OSLC debug session" main/log4j-20211018-1137-19.log main/log4j-oslc-20211028-1235-14.log The result will look like this: 2021-10-27 18:37:54,336 [Monitoring] INFO com.polarion.platform.monitoring - Executing action 'system.info.memory.oldGen.free' 2021-10-27 18:37:54,336 [Monitoring] INFO com.polarion.platform.monitoring - system.info.memory.oldGen.free (Free Old Gen memory after GC) = Java Heap Memory Old Gen pool has 88.51% memory free after GC. [Wed Oct 27 18:37:54 CEST 2021] 2021-10-27 18:37:54,505 [Monitoring] INFO com.polarion.platform.monitoring - Finished with actions from stage PERIODIC: {OK=6} *** Starting the OSLC debug session ## Decide on what to review ### Review incoming requests to Polarion Incoming requests are listed in the access log. Polarion comes bundled with a tool that dispatches all incoming requests to the Polarion app. That tool is called the Apache HTTP Server. This is the tool which provides the log for incoming requests, called the access log. Logs for this are either available at `/data/logs/apache` or `/var/log/httpd`, depending on the underlying operating system. You should have some `access.log.-` file or a `access_log` file. For an advanced access log format, you can expand this section. The LogFormat directive can be highly customized to include as much data as possible. This has been tested successfully on Linux deployments. This directive can be updated in the `httpd.conf` file, in the `` block. LogFormat "\"%h\" \"%u\" \"%t\" \"%D\" \"%r\" \"%s\" \"%B\" \"%m\" \"%U\" \"%q\" \"%a\" \"%A\" \"%C\" \"%{Referer}i\" \"%{User-Agent}i\" \"%{Cookie}i\" \"%{Authorization}o\" \"%{Set-Cookie}i\" \"%{oslc_config.context}i\" \"%{OSLC-Core-Version}i\" \"%{Content-Length}i\" \"%{Accept}i\" \"%{Content-Type}i\" \"%{If-Match}i\" \"%{If-Modified-Since}i\" \"%{X-If-Modified-Since-XSD}i\" \"%{Forwarded}i\" \"%{X-Forwarded-For}i\" \"%{Location}o\" \"%{Content-Location}o\" \"%{Content-Disposition}o\" \"%{eTag}o\" \"%{x-com-sodius-logout-url}o\" \"%{x-com-sodius-logout-method}o\" \"%{X-com-sodius-oauth-redirect-location}o\" \"%{X-com-ibm-team-repository-web-auth-msg}o\" \"%{X-Sodius-Resource}o\" \"%{WWW-Authenticate}o\" \"%{Last-Modified}o\" \"%{Access-Control-Allow-Origin}o\" \"%{Vary}o\" \"%{Origin}o\" \"%{X-Frame-Options}o\" \"%{Content-Security-Policy}o\" common Which gives out the following log: "10.100.99.5" "-" "[16/Jun/2020:07:41:36 +0200]" "628158" "GET /secollab/web/clm/review/67082340-c545-4c86-acd7-7cd1ea2fda08/finalize?oslc_config.context=https:%2F%2Fclm-605.sodius.cloud:9443%2Fsecollab%2Fclm%2Fservices%2Fconfig%2Fstream%2F213e8151-5010-4722-a996-d1f64df4944e HTTP/1.1" "307" "0" "GET" "/secollab/web/clm/review/67082340-c545-4c86-acd7-7cd1ea2fda08/finalize" "?oslc_config.context=https:%2F%2Fclm-605.sodius.cloud:9443%2Fsecollab%2Fclm%2Fservices%2Fconfig%2Fstream%2F213e8151-5010-4722-a996-d1f64df4944e" "10.100.99.5" "10.100.2.102" "JSESSIONID:0000Voxgdm9kVpWRykb_1CGRSVN:5c53c125-1133-4b4d-ba65-e9e16fe6471e LtpaToken2:fjhBhxSwdPdirZzMIvZrff57j4FlS+lk/AtmCinLpdV/MER1cRHFvfAU2yrQF/YbxHEEZOKBDrrgN2BDEuOMkgVJBIjBOmM7pnioeXweRou7h9RnMMYdeCy2ePd02Ix8n8i2pUZyrfwd55apC6rQLsWIZFWjJN9lpRZrrIq5Ok3vsKsIzfv9idGIJpFhOUx6jTQuqfVOpYX4wpJ+jUuHYTDu6slRDe9pQBlw7OT5qWn8TW59WeKDVXrtFbWRo7POvNEfH1uEd4Ec3RBc5bxihsWPnKPL3eGGmLuFsaxatkMNgJkCKd5HUwAgz3YGRXeb" "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:77.0) Gecko/20100101 Firefox/77.0" "JSESSIONID=0000Voxgdm9kVpWRykb_1CGRSVN:5c53c125-1133-4b4d-ba65-e9e16fe6471e; LtpaToken2=fjhBhxSwdPdirZzMIvZrff57j4FlS+lk/AtmCinLpdV/MER1cRHFvfAU2yrQF/YbxHEEZOKBDrrgN2BDEuOMkgVJBIjBOmM7pnioeXweRou7h9RnMMYdeCy2ePd02Ix8n8i2pUZyrfwd55apC6rQLsWIZFWjJN9lpRZrrIq5Ok3vsKsIzfv9idGIJpFhOUx6jTQuqfVOpYX4wpJ+jUuHYTDu6slRDe9pQBlw7OT5qWn8TW59WeKDVXrtFbWRo7POvNEfH1uEd4Ec3RBc5bxihsWPnKPL3eGGmLuFsaxatkMNgJkCKd5HUwAgz3YGRXeb" "-" "-" "-" "-" "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8" "-" "-" "-" "-" "-" "-" "https://clm-605.sodius.cloud:9443/ccm/oauth-authorize?oauth_token=fdfb3353c8ae4387880b5e63aa6095f4" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" "-" Log parameters used in this recommendation are: * %h Remote host * %u Remote user according to the WebSphere Application Server specific $WSRU header * %t NCSA format of the start time of the request * %D The elapsed time of the request - millisecond accuracy, microsecond precision * %r First line of the request * %s Status code of the response * %B Response size in bytes excluding headers. 0 is printed instead of - if no value is found. * %m Request method * %U URL Path, not including the query string * %q Output the query string with any password escaped * %a Remote IP address * %A Local IP address * %C Cookie Retained HTTP request headers are: * Referer * User-Agent * Authorization * Cookie * Set-Cookie * oslc_config.context * OSLC-Core-Version * Content-Length * Accept * Content-Type * If-MatchIf-Modified-Since * X-If-Modified-Since-XSD * Forwarded * X-Forwarded-For Retained HTTP response headers are: * Location * Content-Location * Content-Disposition * eTag * x-com-sodius-logout-url * x-com-sodius-logout-method * X-com-sodius-oauth-redirect-location * X-com-ibm-team-repository-web-auth-msg * X-Sodius-Resource * WWW-Authenticate * Last-Modified * Access-Control-Allow-Origin * Vary * Origin * X-Frame-Options * Content-Security-Policy To make use of the output in Excel: * Copy the below header line to the first line of an Excel Sheet 'Remote host' 'Remote user' 'Request start time' 'Request log time' 'Request duration' 'Request 1st line' 'Status' 'Response size' 'Method' 'URL' 'Query string' 'Cross Component Tracing (XCT) Context ID' 'Remote IP addr' 'Local IP addr' 'Cookie' 'i_Referer' 'i_User-Agent' 'i_Authorization' 'i_Cookie' 'i_Set-Cookie' 'i_oslc_config.context' 'i_OSLC-Core-Version' 'i_Content-Length' 'i_Accept' 'i_Content-Type' 'i_If-Match' 'i_If-Modified-Since' 'i_X-If-Modified-Since-XSD' 'i_Forwarded' 'i_X-Forwarded-For' 'o_Location' 'o_Content-Location' 'o_Content-Disposition' 'o_eTag' 'o_x-com-sodius-logout-url' 'o_x-com-sodius-logout-method' 'o_X-com-sodius-oauth-redirect-location' 'o_X-com-ibm-team-repository-web-auth-msg' 'o_X-Sodius-Resource' 'o_WWW-Authenticate' 'o_Last-Modified' 'o_Access-Control-Allow-Origin' 'o_Vary' 'o_Origin' 'o_X-Frame-Options' 'o_Content-Security-Policy' * Copy the lines you want to investigate to the 2nd+ line of the Excel Sheet *if the copied header or lines are not automatically expanded to columns* 1. Select column Accept 2. In the "Data" banner, click the button called "Text to Column" 3. Choose "delimited", then Next ### Review outgoing requests sent by Polarion, and Polarion processing Polarion logs are located at `/data/logs/` As suggested [here](https://almdemo.polarion.com/polarion/help/index.jsp?topic=%2Fcom.polarion.xray.doc.user%2Fguide%2Fxid1555657.html) in the "Polarion log4j log files" section, you can override the default log4j configuration by copying it to the right place. Once done, one can enable additional logging to help debug potential problems by adding the following block at the end of the newly copied `log4j.properties`: # APPENDER OSLCSODIUS # ================== log4j.appender.OSLCSODIUS=org.apache.log4j.DailyRollingDotMetadataFileAppender log4j.appender.OSLCSODIUS.threshold=DEBUG log4j.appender.OSLCSODIUS.file=log4j-oslc-sodius.log log4j.appender.OSLCSODIUS.append=false log4j.appender.OSLCSODIUS.layout=org.apache.log4j.PatternLayout log4j.appender.OSLCSODIUS.layout.ConversionPattern=%d [%t] %-5p %c %x - %m%n log4j.appender.OSLCSODIUS.datePattern='.'yyyy-ww # Outgoing requests log4j.logger.org.apache.http=DEBUG, OSLCSODIUS # OSLC processing: anything that is Lyo related log4j.logger.org.eclipse.lyo=DEBUG, OSLCSODIUS # OSLC processing: plugin providing most of the OSLC log4j.logger.com.polarion.alm.oslc=DEBUG, OSLCSODIUS You can add everything or just keep the sections that matter to you, depending on whether you wish to investigate OSLC processing issues or outgoing requests issues. ## Finishing the debug session ### Restore your system's previous logging features In the `log4j.properties` file, update the threshold to `OFF`: log4j.appender.OSLCSODIUS.threshold=OFF Then you may `OFF` all the related loggers: # Outgoing requests log4j.logger.org.apache.http=OFF, OSLCSODIUS # OSLC processing: anything that is Lyo related log4j.logger.org.eclipse.lyo=OFF, OSLCSODIUS # OSLC processing: plugin providing most of the OSLC log4j.logger.com.polarion.alm.oslc=OFF, OSLCSODIUS ### Retrieving Polarion logs Open the following most recent log files with this below pattern to see the log entries: `/data/logs/log4j-oslc-sodius*.log` We suggest attaching the log file(s) to a Jira ticket on our [customer support portal](https://sodius.atlassian.net/servicedesk/customer/portal/39) if you think these provide insight into the problem you have identified, or if they were requested. --- version: "Working version" language: "en" --- # Debugging errors using the browser developer tools When troubleshooting complex issues, it is sometimes necessary for our support team to obtain additional information about the network requests that are generated in your browser while an issue occurs. Using developer tools to inspect a web page allows us to: * Identify the errors and warnings reporting by a web page on loading * Identify the network traffic and inspect details of failing requests The advantage here is that the user can examine the issue and retrieve error messages without the need of an Administrator. ## Accessing the Developer Tools For most web browsers to access Developer Tools, **right-click** on the web page, then select **Inspect** or**Inspect Element**. Otherwise access the tool from the Browser menu: | **Browser Name** | **Access from the Menu** | |-------------------|----------------------------------------------------------------------------------| | Google Chrome | More Tools \> Developer Tools | | Mozilla Firefox | Tools \> Web Developer \> Inspector | | Internet Explorer | F12 (Or, go to the Tools menu using press **Alt+X** and select Developer Tools.) | | Safari | Develop menu, then select Show Web Inspector | ## Using the tool **Console** and **Network** are the two tabs that are of most interest. The **Network** Tab gives us a view of the resources that are requested and downloaded over the network in real-time. Choose "Network" tab 1. Refresh the page you're on with F5 or else be sure to open the tab **before** loading a page so that it captures the network requests 2. You'll get a list of HTTP queries that happened 3. Select one of the names in the left-hand column 4. The "Headers" tab shows the request and response headers. 5. Right-click on the Name column of interest and check for error codes 6. Save the HAR (HTTP Archive) file will depend on the browser being used. See the Table below. 7. Attach the file to the Jira Portal ticket. | **Browser Name** | **To generate the HAR file** | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------| | Google Chrome | right-click anywhere on the grid of network requests, select ***Save as HAR with Content***, and save the file to your computer. | | Mozilla Firefox | right-click anywhere under the File column and click on ***Save all as Har***. | | Internet Explorer | Click the ***Save button*** . Give the trace a filename and click the Save button which will save it as a .har file or .xml file. | | Safari | Click the ***Export*** icon on the far right of the network tab and save the HAR file. | ![A HAR Screenshot.png](https://docs.sodiuswillert.com/__attachments/a_7471e287ce98883860e801b1f1bad9e61f1f78f5b828c1b2a9ae8b360412901a/A%20HAR%20Screenshot.png?cb=2db540e62ab9a06696b6049fa8f86e80) *Example for Google Chrome* We are looking for an [HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success) returned by the server. A 200 code is common for a successful response; although anything within the range of 200-299 is considered OK. Error codes like HTTP response code 401 or 500 are shown in red. The **Console** tab The Console has 2 main uses: viewing logged messages and running JavaScript. We're interested in logged error and warning messages especially any error codes that are shown. Steps to perform * Show the Console and look for Error warnings. * Take a screenshot or copy the error(s) * Clear the console as shown below. * Refresh the web page, and then perform the steps that led to the issue. * Copy the content or right-click "Save as" and attach the file(s) to the Jira Portal ticket. ![A console clear.png](https://docs.sodiuswillert.com/__attachments/a_c0a143a1ace8070e76981e534d5ea2b045ddda8bae68aaedd380c7a437743dd0/A%20console%20clear.png?cb=167e98678dd6c28dc9c63318675f984c) --- version: "Working version" language: "en" --- # Demystifying Link Discovery with Global Configurations The ability to have linked data and configuration management is a defining feature of IBM ELM and a bit of a mystery to users (especially when things don't go as expected). We aim to remove the mystery and aid teams in managing their configuration-managed enterprises without surprises. IBM ELM uses link discovery to provide bidirectional linking across versioned artifacts. The straightforward idea is that a link is owned by one resource and stored only on one resource to improve maintainability (no synchronization of endpoints needed!). The side-effect of this pattern is that it creates the responsibility of the target to "discover" any references to itself and present it just the same as an owned link. An example is a link from a Jira Story to a DOORS Next requirement. Jira stores the link and link type on its artifact. It also stores the Jira version(s) in which this link is active. DOORS Next is then responsible for performing a query to ask if any inbound links relate to the requirement within the current context. Then, DNG shows owned and discovered links as the same to the user. This is the idea of link discovery. Following, we break down these to dispel the magic and remove the surprise of when links appear (or don't appear) ## The Pieces in Practice In practice, each tool plays a role in the link discovery process. Following the scenario of Jira to DOORS Next, these are the roles the tools play. ### IBM GCM GCM's role is to provide context. It sets the version of artifacts that users want together by selecting a set of local streams of artifacts. In addition, it sets a context for what Jira Versions should be used to select the Jira items of interest. ![image-20240306-192316.png](https://docs.sodiuswillert.com/__attachments/a_95e505be99bc54d95d0b11869b15f86eed1885e63c27e26e251823035b4b0b01/image-20240306-192316.png?cb=74a1ebd619718ec4516b585271a7bc94) ### (OSLC Connect for) Jira The role of Jira is to define the change artifact, store the link (with a specific relationship), and identify the versions those links apply to. This allows the links in Jira to point to a particular resource in DNG and have the dynamics we expect with OSLC. ![image-20240306-192910.png](https://docs.sodiuswillert.com/__attachments/a_b5bd438ece174d14a28da3b7715ff6c0631d73e8f44f524f6b9cdb42af7deb62/image-20240306-192910.png?cb=0fb82efc11f065104102f2aba4641260) The OSLC Connect for Jira tool is also responsible for sharing the information from Jira so it can be indexed for queries. This is an expression of the artifact, including link and version information. ### IBM DOORS Next The role of DOORS Next is to store requirements and their links. However, it does not store links for change or test artifacts, so it has the secondary role of querying for those artifacts when it displays a requirement. ![image-20240306-193635.png](https://docs.sodiuswillert.com/__attachments/a_29af22ae11d48f389682bd4f1a65b06b46b6619d80f44ed6ef39a941bee55928/image-20240306-193635.png?cb=41fc5ac5984c7b399bfb2662dc686a4c) You will note that for performing queries, DNG uses the context of the current GC to formulate the query. ### IBM LDX (Link Index Provider) The link index provider (LDX) reads data sources (like Jira through its TRS feed) to provide query services. In this role, LDX aggregates data from multiple tools to facilitate link discovery. In most deployments, LDX indexes data from GCM, ETM, and EWM. As an additional OSLC participant, we also introduce Jira data. ![grab470.jpg](https://docs.sodiuswillert.com/__attachments/a_fe791a9fa98afd1d35eaa2de364f641e80873ffaf315c2840217d9bd5ba44538/grab470.jpg?cb=a3c70321d4877cfa52e9e010cc601276) The LDX service provides the query service to identify the information a tool like DNG needs to show inbound links. ## A Detailed Demonstration of the Discovery Process Following is a tour of all of the activities that are executed to facilitate the discovery process. ### Feeding the Data Feeding the data focuses on what information LDX requires to perform the query. #### From Jira Jira is providing two resources to LDX. First, the Jira issue and its attributes (including links). The attached file is a sample of the raw data of a Jira issue provided to LDX. Note in most deployments, there are thousands if not millions of these artifacts that are read and indexed from Jira. [AMRPRT-1 (4).xml](https://docs.sodiuswillert.com/__attachments/a_a8ba38e6a91b95d1ccd9a3027e9dcd196cc90f09fb2dcb5f810019a715105d04/AMRPRT-1%2520(4).xml.md?cb=8a36ee5f2167ddd361972c71827c1801) And the Jira Release. The attached file is a sample of the raw data for a Release that LDX consumes. [Version 2.xml](https://docs.sodiuswillert.com/__attachments/a_0a40ff93dacbe7d935066e428e9273e45994282dd273726da35cc4540ff2a40a/Version%25202.xml.md?cb=658d4e2bd15180b08eb55d612bce4731) The Jira TRS feed tracks these objects for change and identifies when they need to be re-indexed (read) by the indexer as a list of changed artifacts. #### From GC GCM defines the Global Configuration to LDX. Each GC provides a resource description, like the attached, that describes the configuration's contents. [AMR Version 1.xml](https://docs.sodiuswillert.com/__attachments/a_3cf080cc9a3fb570894e1e42bb772a0d68651aa4602e8a5cdfa15f5ff1512ca4/AMR%2520Version%25201.xml.md?cb=ecdfaf82feb088e6666c70ff30f9e536) Similar to Jira, the TRS feed for GCM regularly updates with which definitions have changed and must be re-read. #### LDX LDX constantly polls the data sources (roughly once a minute) and updates its index accordingly. By reviewing the documents above, you can see how the index uses the URLs to make connections from a Jira issue to Jira links, to Jira Deliverables, and Global Configurations. This creates a graph of relationships that LDX uses in many different queries. ### Consuming the Data Once the data has been indexed, a given target can use it to discover the links. Viewing a DNG Requirement, focusing on requirement 463 in module 370. From an OSLC perspective, its identifier is the URL → ![image-20240306-202651.png](https://docs.sodiuswillert.com/__attachments/a_473f9315eafeaa442bdc1d4e1354164690429bdb71160670b54b68ac5dcd0a03/image-20240306-202651.png?cb=9606796d3bca6bf055a406f36f081aec) When displaying this, DNG will make two internal requests to find links. This internal REST API ([https://myDNGServer/rm/links](https://mydngserver/rm/links)) has a payload of an artifact URL and a configuration URL. It is called once for this module-bound resource and second for the base requirement resource. The result is the URLs of the links and the relationship type. It looks like the following: ![image-20240306-204819.png](https://docs.sodiuswillert.com/__attachments/a_4c2ba561758e1a638da6a9016c9dc39ecdf6a73d4818025fd609e7183aa86b03/image-20240306-204819.png?cb=a9435d4b4a5c585bdc9abcdc3fdc3947) ![image-20240306-204841.png](https://docs.sodiuswillert.com/__attachments/a_5f2b48a8df26cdf007fd06f777edef4c67972ce03a2e11e36add84255fe2b636/image-20240306-204841.png?cb=443f259bbe482969862137020ba3db39) The result includes both discovered and owned links. However to formulate this response DNG relies on LDX for the discovery. This query looks as follows (and can be tracked in LDX). prefix dcterms: prefix oslc_config: prefix rdf: prefix owl: prefix rtc_cm: SELECT DISTINCT ?sURL ?linkType ?tURL ?indLinkType WHERE { { VALUES ?linkType { } VALUES ?tURL { } VALUES ?config { } { ?sURL ?linkType ?tURL. BIND( ?linkType as ?indLinkType ) . } UNION { ?indLinkType owl:sameAs ?linkType . ?sURL ?indLinkType ?tURL . } } OPTIONAL { ?reification rdf:subject ?sURL . ?reification rdf:predicate ?indLinkType . ?reification rdf:object ?tURL . ?reification rtc_cm:deliverable ?release . ?reification rtc_cm:deliverable ?linkRelease . } OPTIONAL { ?config rtc_cm:deliverable/rtc_cm:releasePredecessor* ?configRelease . } FILTER (!BOUND(?reification) || (BOUND(?linkRelease) && BOUND(?configRelease) && ?linkRelease = ?configRelease))} LIMIT 1000 In this, you can see the URL of the module-bound requirement, the link types it is interested in, and the global configuration in which it is interested. The result is the Jira Artifact which is linked. ![image-20240306-204231.png](https://docs.sodiuswillert.com/__attachments/a_28e79480d71c11ab3b76916d76eb3dd4f519a034379eb823262e2cf44718b714/image-20240306-204231.png?cb=52a23b97f940d66046fe0b7cdd9f16ec) ***This is what we mean when we say discovery. The link isn't stored on the requirement; rather, a query is issued to "discover" inbound links (all the relationship types in the query).*** Note that only the URL of the Jira artifact is returned. To get more details, DNG will request them back from Jira. #### Exploring More If you are looking to understand more, DNG (and QM) to reveal a debug screen to their query service. You can find it at [https://myDNGServer/rm/linkIndex/query.](https://mydngserver/rm/linkIndex/query.) You will see a simple dialog with the parameter of the internal query. The "options" link will provide more details than I describe here. ![image-20240307-134708.png](https://docs.sodiuswillert.com/__attachments/a_d0d118805d2f34de5fd2c104355f8a47b82220578c04783453fef8b2c7c95739/image-20240307-134708.png?cb=bc6bb2d89b31dd26e767a2c023747270) Add your RM resource URI, the link types you are looking for, and the GC configuration. This service will then compose and request the execution of the LDX SPARQL query. ![image-20240307-135309.png](https://docs.sodiuswillert.com/__attachments/a_2c90f6b823d39ba1cfa2db8b6916f816cc2036e6896fb0687b543358b514232a/image-20240307-135309.png?cb=1c70f9038442cd59b14c5479e538a9f7) And you can observe the execution in LDX. Navigate to [https://myLDXServer/ldx/web/health/query-stats.](https://myldxserver/ldx/web/health/query-stats.) ![image-20240307-135440.png](https://docs.sodiuswillert.com/__attachments/a_7a6ef8f8f77bb6c3bcc4495792b41c21cf659d10697688dd7b0e62f1ff0ba1b4/image-20240307-135440.png?cb=03f3819ccd24a4334b06097e1e3025ba) Here, you can review your last queries, performance, and construction. For example, the last query I requested from the RM looks like this: ![image-20240307-135625.png](https://docs.sodiuswillert.com/__attachments/a_5cddcbb6fe7de7205412a9eaf746e68af25c1c8e7277f0dd271d608477115845/image-20240307-135625.png?cb=6ed260ed7d7a835342c603bd0a68b74b) It is a form structure with only the link I am interested in (rather than the more broad search that DNG is doing for users). Feel free to experiment and understand more about the discovery tools in IBM ELM. ## When Discovery can be unsuccessful If Discovery doesn't return the data expected, it is because of one of the following * Data isn't accurate (examples ... missing versions in Jira or GC) * Data isn't up to date in LDX (paused or missing data sources) See our article on inspecting the contents of LDX to understand better where the failure may have occurred [Checking the Contents of LDX](https://docs.sodiuswillert.com/oslc-connect/latest/checking-the-contents-of-ldx.md) --- version: "Working version" language: "en" --- # Downloading OSLC Connect for Jira Cloud OSLC Connect for Jira Cloud is composed of two components; a Forge application and a Broker application. The OSLC Connect for Jira Cloud Forge Application is available on the Atlassian Marketplace. This can be viewed/installed from . The OSLC Connect for Jira Cloud Broker Application is available directly from SodiusWillert. The download links are available below. Latest Broker Application → There is no licensing for the Forge Application. Trial and Subscription licenses for Broker Application are available from the SodiusWillert team. Please send a support request to [cusoslcjra@sodiuswillert.atlassian.net](mailto:cusoslcjra@sodiuswillert.atlassian.net) to obtain a license. --- version: "Working version" language: "en" --- # Embedded Content or Authentication Isn't Working between OSLC Applications ## Introduction Interactions between OSLC applications rely on browsers to interact using web protocols. Critically, browsers manage our sessions and authentication status using stateful information stored in *cookies*. Traditionally, web-browsers have been very flexible to the usage of cookies, enabling embedded content, and usages across sites. There have been concerns in the usage of cookies across sites for which the community has been changing default cookie behavior for the embedded content. OSLC integrations are prone to impact because they regularly embed content from remote applications such as selectors, previews, and login prompts. When all your repositories are in the same root site (e.g `elm.mycompany.com` and `oslc-connect.mycompany.com`) there are no changes in behaviors. However, if the repositories are in different root sites (e.g. `mycompany.com` \& `myhostingcompany.com`) then the new default browser behavior can cause users issues. ***The issues we observe that have been deployed are authentication issues (loops) and embedded content (selections or previews) are not displayed. Effectively, your OSLC Integration will appear broken.*** ## The Basic Details The browser community has instituted a change in the default behavior of security policy on cookies. Every cookie is given a SameSite (and Secure) property that dictates how a browser will utilize the cookie across sites for the embedded content. The newly instituted behavior is to default the SameSite property to more restrictive behavior for all cookies that do not specify a value. This default SameSite setting (assigned as 'Lax') will prohibit the use of the cookies in an embedded context when they reside in different sites. The result is your OSLC applications will not have accessible embedded content and will have authentication issues for this embedded content. ## How to Verify the Root Cause If, once you authenticated to the remote tool, authentication is not working (often a flashing login, or you're sent back to the authentication page without an error) and/or your embedded content is not visible, it is most likely this SameSite issue. First, inspect and confirm that OSLC Applications are on different site roots. Root causing with Chrome A user can do a quick determination of the cause by validating the following in Chrome (versions between 80 and 91). Navigate to `chrome://flags` and disable `SameSite by default cookies` and `Cookies without SameSite must be secure`. Example in the screenshot below. ![image-20210113-193212.png](https://docs.sodiuswillert.com/__attachments/a_2e05de93e068396e96408cfd282eaebbb676ec5bd8f928dd1a35daadb5ec0248/image-20210113-193212.png?cb=7994a2c0eb186476434f36f4a281f12f) Relaunch Chrome and attempt the OSLC behaviors of authentication, linking, and previews. If the behavior works, you will need to see the next section on how to fix it. As a workaround, all users can leverage this capability of Chrome while the resolution is made more permanently. Root causing with Firefox A user can do a quick determination of the cause by validating the following in Firefox (versions 96+, since prior versions, unless otherwise configured, default to having that configuration disabled). Navigate to `about:config`. Search for `laxByDefault`. The first result should be `network.cookie.sameSite.laxByDefault`. ![image-20211213-102237.png](https://docs.sodiuswillert.com/__attachments/a_ff864401833634f9238e7c8b1f776ab655e2241fe4acc8aa2566f35eaa37c5ac/image-20211213-102237.png?cb=c6ba29236a020a3205581575ebbfac8b) If the value is `true`, try setting it to `false`. Relaunch Firefox and attempt the OSLC behaviors of authentication, linking, and previews. If the behavior works, you will need to see the next section on how to fix it. As a workaround, all users can leverage this capability of Firefox while the resolution is made more permanently. Note: for a secured and consistent experience across browsers, we recommend users set this value to true. If it doesn't work, and it is only the preview content, it could be an HTTP header issue, such as Content-Security-Policy or X-Frame-Options, and you should see the following technote [Rich Previews/Dialogs not visible?](https://docs.sodiuswillert.com/oslc-connect/latest/rich-previews-dialogs-not-visible.md) ## Permanent Resolution The permanent resolution is that your OSLC Applications must explicitly set the SameSite=None and the Secure flag. When this is set by the application for its cookies, the browsers are able to leverage cookies and embed content as is natural with OSLC. *** ** * ** *** If the authentication fails when using an OSLC application, such as ELM or Polarion, and trying to connect to an OSLC Connect application, you should use the features offered by the Security page in the server administration of your OSLC Connect application: * for OSLC Connect for Jira, please [review the documentation here](https://help.sodius.cloud/help/topic/com.sodius.oslc.app.jira.doc/html/admin/server/security.html) Typically, we would expect you enable the *Sharing Cookies* toggle. Additionally, if using a customized authentication, you should also enable the *advanced login solutions* toggle. ![index.png](https://docs.sodiuswillert.com/__attachments/a_48992b20a421fbdd35952a1384f18ff1f6daa1042845bc60735ff22c95bd994a/index.png?cb=58c0de6e23d07cb7766bd49b9c2309ad) *** ** * ** *** If the authentication fails when using an OSLC Connect application and trying to connect to a remote OSLC application, it means you must update the remote OSLC application's configuration. The setting of cookies is the Application and Web App server specific. It is recommended that this change be reviewed with your Web App server team and your Application vendor. For reference guidance, you can review information from vendors. Examples include: * For IBM Websphere Application Server, see [this IBM Support Article](https://www.ibm.com/support/pages/browser-changes-samesite-cookie-handling-and-websphere-application-server) * For Polarion, see the bottom of [this article](https://almdemo.polarion.com/polarion/help/index.jsp?topic=%2Fcom.polarion.xray.doc.user%2Fguide%2Fxid1551488.html&cp=0_3_15_2_1) from the Polarion documentation * For Apache Tomcat (in 9 series 9.0.28+ and in the 8 series 8.5.48+), inside the META-INF folder create a context.xml file to [add/update the CookieProcessor tag](https://tomcat.apache.org/tomcat-9.0-doc/config/cookie-processor.html), such as: |-----------------------------------------------------------------| | | --- version: "Working version" language: "en" --- # Example Creating OSLC Links with Python We have noticed some OSLC Connect users with IBM ELM want to bulk import some OSLC Links. If you are using Global Configuration, the Links are only stored in Jira, and you can rapidly import links using the Jira API. ***Note that when using this technique, OSLC Connect does not validate your links, targets, or GC context. The validity of the links created will be up to the script creator and executor.*** We are starting with a simple Excel spreadsheet. This has a Jira Key, a Link Type, and Target Resource(s). The target resources are the URIs for the DNG Requirements. [Example.xlsx](https://docs.sodiuswillert.com/__attachments/a_86f9658bba65ef60123d0707e7c1dbadf7ac8abc664f7497e8f55863449c1745/Example.xlsx.md?cb=8ed39ceb2e087b1546a6d5abf7da8af6) We are then using a basic Python script that will read the Excel file (using Pandas), Use REST APIs with Jira (using requests), and then inspecting and creating Json content for the body of our requests. We have documented the script so users can learn and update it. Python # Simple demonstration of reading an excel file to create some OSLC links in Jira # # Format of the XLS file is # # Jira Key, Relationship Type, Target URL (in this case DNG) # # Basic flow is to # 1) Read XLS # 2) Iterate across Rows (do any parsing) # 3) Check to see if a link already exists # 5) Add remote link if needed # # Note, we are not checking the validity of the end-points or the proper formating of # the relationship type, or extracting the remote title. # # Note, optimizations can be done, but this is a demonstrator not intended for performance optimizations # imports import pandas as pd import os from dotenv import load_dotenv import requests from requests.auth import HTTPBasicAuth import json def checkForLinkExisting ( JiraKey : str, LinkType : str, LinkTarget : str, ) -> bool : # Check to see if a link exists already # Get the remote links on the artifact # Inspect if the link already exists url = f"{jiraRoot}/rest/api/latest/issue/{JiraKey}/remotelink" existingLinks = requests.get(url, auth=basic, verify=False) if existingLinks.status_code == 200 : linksObj = existingLinks.json() for link in linksObj : if link['application']['type'] == 'com.sodius.oslc.app.jira' : if link['relationship'] == LinkType : if link['object']['url'] == LinkTarget : # link already exists, return true return True # no link found, return false return False def addToggleUpdate ( JiraKey : str, ) -> bool : # Request an issue and then add a space to trigger change detection url = f"{jiraRoot}/rest/api/2/issue/{JiraKey}" headers = {'Accept': 'application/json'} existingIssue = requests.get(url, headers=headers, auth=basic, verify=False) if existingIssue.status_code == 200 : # get the content issueObj = existingIssue.json() description = issueObj['fields']['description'] if not description: description = " " # Add a simple space description = description + " " headers = {'Content-Type': 'application/json'} body = json.dumps( { 'key':jiraKey , 'fields': {'description':description } } ) issueUpdate = requests.put(url, auth=basic, headers=headers, data=body, verify=False) if issueUpdate.status_code == 204 : return True else : print("Unable to update Jira issue. Status Code " + str(issueUpdate.status_code) ) return False def addLink ( JiraKey : str, LinkType : str, LinkTarget : str, LinkTitle : str = "Generated Title", ) -> bool : url = f"{jiraRoot}/rest/api/latest/issue/{JiraKey}/remotelink" headers = {'Content-Type': 'application/json'} # Now build the Json structure https://developer.atlassian.com/server/jira/platform/jira-rest-api-for-remote-issue-links/ # With OSLC specific configuration https://docs.sodiuswillert.com/oslc-connect/latest/understanding-oslc-connect-for-jira-link-storage # { # "application": { # "type": "com.sodius.oslc.app.jira", # "name": "Collaboration Link" # }, # "relationship": LinkType, # "object": { # "url": LinkTarget, # "title": "Generated Link", # } # } body = json.dumps( {'application': { 'type' : 'com.sodius.oslc.app.jira' , 'name' : 'Collaboration Link' }, 'relationship' : LinkType , "object" : { 'url' : LinkTarget, 'title' : LinkTitle} } ) addLink = requests.post(url, auth=basic, headers=headers, verify=False, data=body) if addLink.status_code==201 : if jiraKey not in updatedItems : updatedItems.append( jiraKey ) return True else : return False # Load our user password information from file load_dotenv() basic = HTTPBasicAuth(os.getenv('JIRA_USER_ID'), os.getenv('JIRA_USER_PASSWORD') ) jiraRoot = 'https://phoenix-jira.sodiuswillert.cloud' links_df = pd.read_excel('example.xlsx') print(f'Inspecting {len(links_df)} to create links') updatedItems = [] # Interate across our rows in our Excel file (now in a data frame) for i in range(0, len(links_df)): # Need to split the link Target row = links_df.iloc[i] jiraKey = row['Jira Key'] linkType = row['Link Type'] # Getting the targets of the links. Assuming multiple and removing the Query parameters targets = [text.strip().split('?')[0] for text in row['Target Resource'].split(",")] for target in targets: linkExists = checkForLinkExisting( jiraKey, linkType, target ) if not linkExists: print(f'Creating Link on {jiraKey} to {str(target)}') addLink( jiraKey, linkType, target ) else: print(f'Skipping Link (already there) on {jiraKey} to {str(target)} of {str(linkType)}') # Optional. If using IBM ELM, it is useful to toggle all items so TRS updates are made print (f'Toggling {len(updatedItems)} Jira Issues for TRS Updates') for issueItem in updatedItems: update = addToggleUpdate( issueItem ) if update: print (f'Set modifed status for {issueItem} in Jira') If using IBM ELM, there is a small update to toggle the description (see line 143) to trigger TRS modification event. If not using ELM, you can skip this behavior. All scripts are provided as is. Users are responsible for testing and validating the behavior. The purpose is an example of what is possible. Enhancements or customizations can be requested and performed under a Statement of Work. --- version: "Working version" language: "en" --- # Example of Using DOORS Next with XRay with OSLC ## Overview Configuring your Jira installation (with XRay) with the QM mappings will make integrating with IBM DOORS Next more powerful. Now, you can reference your test artifacts directly to Requirements in DOORS Next. In DOORS Next, you will have access to Test on Requirements directly on the Validated By links, as you would expect tests to be. This improves the reporting situation, where you can build more complex reports and improve the clarity of the difference between change and test objects. ## Connecting from Jira to DNG Configurations First, let's focus on connecting from Jira to DOORS Next. ### Adjusting Type Schemes for Xray Types The "Issue Types Mapping" for OSLC Connect (in Manage Apps) allows teams to declare many important values about their Jira artifacts on how they connect externally. These options are tied to Jira Schemes, so you can align workflows and actions across many projects. By default, OSLC Connect targets Change Management Artifacts. You will see this when you open your Scheme's configuration. ![image-20250116-174638.png](https://docs.sodiuswillert.com/__attachments/a_664b40d46f577f55816408f5fb880774462f51431b2f075a2e282c43c12ad6b8/image-20250116-174638.png?cb=f1856df8075d6bea25fb73a95930f27e) When you are using Xray we do detect that some elements look like QM artifacts, so you can click on the "Do you want to associate them?" to create some default mappings. ![image-20250116-174811.png](https://docs.sodiuswillert.com/__attachments/a_55afdfbdf7d4addbc35b360d6e8f956e8fd1cb0795cca73b4997d3e25f595667/image-20250116-174811.png?cb=4eb787dc18555fc6336797afe2b9549d) The result is the following: ![image-20250116-174918.png](https://docs.sodiuswillert.com/__attachments/a_97560180d4359916d2dabf378df91409ed935eab25aceecba4ca229edb8bc4bb/image-20250116-174918.png?cb=f5c0d903bc735671b83c4c6e2db9268f) I'm going to further customize this to disable some elements from DOORS Next and set some defaults. When I unmap the OSLC Resource Type this means I am not supporting linking from DNG to these artifacts. ![image-20250116-175149.png](https://docs.sodiuswillert.com/__attachments/a_3060baf769d19b79958f9d36af3a42ea61c03e37b1152ca99426cd95453815f2/image-20250116-175149.png?cb=e1da80900c88342399ae03f0db3ef5ec) I also updated Sub Test Execution to a Test Execution Record to enable linking and reporting For each item, I can now set the Edit Link Settings. On one Tab, I set the label I will see from DNG, for example: ![image-20250116-175440.png](https://docs.sodiuswillert.com/__attachments/a_cfda93645adccb0509cb46e04d1cb218013a99964a812a30bf0d9d2e269e88e7/image-20250116-175440.png?cb=54a04b892389621277dde6d465773dd7) On the other tab, I changed the linking behavior from Jira to other tools (limiting the available link types). ![image-20250116-175551.png](https://docs.sodiuswillert.com/__attachments/a_a3e130ca1b84ec94f9c1fe3069c804014efc4defafad6a9660fa2a14e1769956/image-20250116-175551.png?cb=350de00d985b2d1fed30dd38af753def) Once I am done, I will have an overview of the configurations for my scheme. ![image-20250116-180150.png](https://docs.sodiuswillert.com/__attachments/a_eecba62c1554396c05b247db5563f048fbe0074acd501aa3ceaa7295a9155648/image-20250116-180150.png?cb=2accbb83ef4d7fbb78e2513b2cb9e868) This is an example configuration. Your configuration may be different based on your needs. ### Creating Project Associations We must create project associations to link to DOORS Next from your XRay Tests. On your project settings, look for OSLC Connect Project Associations. ![image-20250116-180458.png](https://docs.sodiuswillert.com/__attachments/a_90451b4041e4eb2d8ee26d8c2719fb0f137d9bcb315a5f032d05d35855286c66/image-20250116-180458.png?cb=5851101c5d17f50a4b1e96661df7de17) Add a DNG RM project. ![image-20250116-180617.png](https://docs.sodiuswillert.com/__attachments/a_b2a00b299bfc072032f05dfaa48a6521b7a963e6689b9c16f8175a16f857a399/image-20250116-180617.png?cb=bf93d8ad88cb9ac65fb731f3ac9c51c5) Now, your Jira project knows what RM projects can be used for linking. #### If you are using GC Enabled RM projects Using GC is very common. And our tooling does support GCs. In project settings → OSLC Connect → Global Configurations. Ensure your project is configured for configurations. ![image-20250116-180908.png](https://docs.sodiuswillert.com/__attachments/a_6a0adec0fecb4da6de51ea1284158d6f83c76ad83087d3788e621f8e1d9ec7f3/image-20250116-180908.png?cb=81d521fdb97dae4cf20820522cd0c20d) To set the context for your RM links, set your versions to the GCs you want to link to. Consider this idea is if you have created a Test Case for Version 1, this is the GC for the Requirements you are testing. ### Linking to DOORS Next Now, when navigating to a Test, you can start creating Links. In this link dialog, you see many of the configurations you have created. A Test is an "OSLC Test Case" type, so it supports these relation types. We focused on the Validates Requirement Relationship and connected only to the AMR-XRay project. ![image-20250116-181524.png](https://docs.sodiuswillert.com/__attachments/a_ad02a2483566c13059f2ea18b1daceaa2a2c1abc4452f55f6c72951c12bda4d0/image-20250116-181524.png?cb=d113e3940b9dbe9e69861c450046b048) We then can see the requirements in this container in the "AMR - X Version 1" configuration (because it was mapped to Version 1 which is in the Fix Version of this Test) ![image-20250116-181803.png](https://docs.sodiuswillert.com/__attachments/a_c695089f1c74e5ffa31c940cd65681b9f1c4bd7d7e29910b86f8213eac05d8b3/image-20250116-181803.png?cb=bdb8951922a695d12826a749725e048b) Once we select one or more requirements, we can see them live on the ticket. ![image-20250116-181915.png](https://docs.sodiuswillert.com/__attachments/a_3759a620aecec8f7aeaca8060249b9200240adee755e70787aec0d4669edfb40/image-20250116-181915.png?cb=1e43aef2ac0aba8e16bc5e7a93e55d8f) You now have live access to your versioned requirements from your XRay Test! ## Leveraging IBM ELM with XRay Following is a quick primer on how to get the IBM ELM side of the integration quickly valuable. ### Project Associations In DOORS Next, you need to Add Associations. If you are familiar with the OSLC Connect for Jira tooling you will expect, the "Uses" relationships, the new one is the "Provides". ![image-20250116-182732.png](https://docs.sodiuswillert.com/__attachments/a_5488b06a4372311b3c4ed03f701d6cbbf5fc4e47b2c3f4abc41403e7b6748d11/image-20250116-182732.png?cb=d86d9f34d9397cb8feba9107a75b4286) When you select that option you will see all the Jira projects with QM artifacts defined. ![image-20250116-182828.png](https://docs.sodiuswillert.com/__attachments/a_38ccf66bef2b6d92739bdeb39b93605fa10c4c3709a4260656f791c033f5fd62/image-20250116-182828.png?cb=74ce0c27b6fde950fcfe360d938c50ab) Note there is a (QM) suffix on the name of your Jira project for clarity in some other OSLC tools. ### Using GCs (if Applicable) When using GCs, we need to define the test artifacts from XRay projects that we expect in a specific configuration. We provide a simple mapping where XRay artifacts can be mapped into a GC using the established Jira Version. You will see that in your GC, you can add a configuration from Jira. ![image-20250116-183602.png](https://docs.sodiuswillert.com/__attachments/a_8f35d182747d39248cd7a6a4fad2dc280056ad9addb52bd2bc9e73db2546fecd/image-20250116-183602.png?cb=13fc4b2dc324de08d188ab342ccb4c95) Select the XRay Configuration you want to use. ![image-20250116-183641.png](https://docs.sodiuswillert.com/__attachments/a_a4a433789c396bfae144159a3f55a49059fa328950d364ccf2f6801213cea4ca/image-20250116-183641.png?cb=2f86f99c8e6dc67c020eca2dd6095868) And then you can see the XRay Component in the Configuration. ![image-20250116-183719.png](https://docs.sodiuswillert.com/__attachments/a_c082b57d19daef4905b6be718b8eb8d60ba3a7a83b98baaf955b0ec8effc8e23/image-20250116-183719.png?cb=26b357f67fe3d18744b3c89ae69ea72f) Simply click on configuration to see what XRay items are in that configuration. ![image-20250116-183812.png](https://docs.sodiuswillert.com/__attachments/a_bfea6dcd1d2ee2b6f073f72c19f98ec2212b7378c6991183b1ddd73f93f10b09/image-20250116-183812.png?cb=7d30ba8b059e60de3e475af7a9e4b72a) ### Testing adding links With this configuration done, you can create links in DOORS Next. Within the standard DNG screens, you can add a Validated By link. ![image-20250116-184139.png](https://docs.sodiuswillert.com/__attachments/a_1b9533b4b72416eac112dea932cec78d67003980dcb93a6990fdf86bbc50e43a/image-20250116-184139.png?cb=adf84153c3bab5e7fa649edc55e2e074) From this point you can select whether to choose an existing item, ![image-20250116-184302.png](https://docs.sodiuswillert.com/__attachments/a_d9f6abae2fd68696336de341d2d2f9d10c79006dc1b124dded425358190dfd07/image-20250116-184302.png?cb=7405aaac5493327c27c1fe0efe322394) or create a new Test Case. ![image-20250116-184340.png](https://docs.sodiuswillert.com/__attachments/a_f26f1fa192868c57cd4e4421e78f7c704a26a782f8ef6ce6db364fbb5bff1923/image-20250116-184340.png?cb=d2af217d16b5b1923dcb33034469f0c0) We will check the type, GC, and other elements to ensure your linkage is valuable. ![image-20250116-184450.png](https://docs.sodiuswillert.com/__attachments/a_dcb6bcec04049ef42c898199016da9d0d00bb3f24a54e7238df13a361658bfb8/image-20250116-184450.png?cb=9cf8b373cb5863c5fd86d2f42383f680) You will immediately see this link stored in Jira and hovers are available from DNG. ![image-20250116-184557.png](https://docs.sodiuswillert.com/__attachments/a_8cdc7f39ccbd86142734aa90f6b304ffc309740e18fa1445cd4ee023bb13e320/image-20250116-184557.png?cb=fbe80aca224f37cb15dff7ac9533668a) Note that if you don't configure LDX, this link will disappear, so please continue and confirm that LDX is configured! ### LDX \& LQE The IBM tools use indexers extensively. The LDX index is used for link discovery. The LQE index is used for Reporting (Report Builder and Engineering Insights). To support using Xray artifacts. We need to add data sources for these tools. In LDX, add a new Data Source for QM Resources. (You most likely already have the CM Resources) ![image-20250116-185858.png](https://docs.sodiuswillert.com/__attachments/a_d75aed921f0f5eb85aa32554142e646925397968e30e9939e77136c4a8721458/image-20250116-185858.png?cb=f76d0b4286448bbda943cc0f350e4c8e) In LQE, you must add both the process resources (if not there) and the QM resources. ![image-20250116-190348.png](https://docs.sodiuswillert.com/__attachments/a_34b6587ab776d61c83ae93c708d444a806ae6337265ebcf10cc175a61c4c7692/image-20250116-190348.png?cb=749e742d72f68bc40dcebe0df986124a) If you have questions about configuring data sources for LQE or LDX, please reference the base install documentation/videos. ### Reporting When fully configured, the QM support allows reporting on XRay elements in Report Builder. You can create reports that communicate requirements to test coverage. ![image-20250116-192032.png](https://docs.sodiuswillert.com/__attachments/a_829c9114d5f3b33b9a7ac8b97e6e4f7c6d6004506541ef768be8c67b774f651f/image-20250116-192032.png?cb=8d86edb7feb5eb7382b3968b49220450) Yielding reports such as ... ![image-20250116-191808.png](https://docs.sodiuswillert.com/__attachments/a_ea75ffa1dab8856fe2658d0b828acde5e6295843274dcdee128e8fb570ece33f/image-20250116-191808.png?cb=9fdbe86ee241da2f49809356686aa25d) For those that are more advanced, we are supporting mapping Jira Native links to OSLC link types. This can enable more complex relationships between requirements, tests, and defects. ![image-20250116-192212.png](https://docs.sodiuswillert.com/__attachments/a_987b331b153b9a43f681e89a41d22ee006ab26bad1a653c461e8f92f97f6c81f/image-20250116-192212.png?cb=1dc66e40fe889055c9e4827eaeddb663) Yielding ... ![image-20250116-192304.png](https://docs.sodiuswillert.com/__attachments/a_ad46053d0df990b2c4b3342b3bcc1176320ceeb2a0b18352c2b3705a64ab3c24/image-20250116-192304.png?cb=a0f889b66f5c1e1e05e5915b53fa9ccc) --- version: "Working version" language: "en" --- # Example of Using Polarion with XRay with OSLC Connect ## Overview Configuring your Jira installation (with XRay) with the QM mappings will make the integration with Siemens Polarion more powerful. You can reference your test artifacts directly to Requirements in Polarion. In Polarion, you can access Tests from Requirements directly on the Validated By links. This improves the ability to have strong traceability across the lifecycle and in reporting on traceability. ## Connecting from Jira to Polarion First, let's focus on connecting from Jira to Polarion. ### Adjusting Type Schemes for Xray Types The "Issue Types Mapping" for OSLC Connect (in Manage Apps) allows teams to declare many important values about their Jira artifacts on how they connect externally. These options are tied to Jira Schemes, so you can align workflows and actions across many projects. OSLC defines a set of resource types for Change, Requirements, and Quality Management (testing) and an overlay for Configuration Management. By default, OSLC Connect for Jira targets Change Management Artifacts, however we are now expanded to other optional mappings. You will see this when you open your Scheme's configuration. ![image-20250116-174638.png](https://docs.sodiuswillert.com/__attachments/a_22b8f1b1b6f571cb75bd6edde9ee13f400df135d629416185204ac6a843686ec/image-20250116-174638.png?cb=f1856df8075d6bea25fb73a95930f27e) When using Xray, we detect that some elements look like QM artifacts, so you can click "Do you want to associate them?" to create some default mappings. ![image-20250116-174811.png](https://docs.sodiuswillert.com/__attachments/a_6e4e8c9ae35d4c110831d0b0a1f6cec72ed702496ecff707a9ee0cc86666822a/image-20250116-174811.png?cb=4eb787dc18555fc6336797afe2b9549d) The result is the following: ![image-20250116-174918.png](https://docs.sodiuswillert.com/__attachments/a_30d8ffac4b712c39c423c37f583ba7f38fc151ebb1350858caf1bf05a0482b5d/image-20250116-174918.png?cb=f5c0d903bc735671b83c4c6e2db9268f) I will customize this further to disable some elements from Polarion and set some defaults. When I unmap the OSLC Resource Type this means I am not supporting linking from Polarion to these artifacts. ![image-20250116-175149.png](https://docs.sodiuswillert.com/__attachments/a_6905f0d0e3d073351a087f9d738bd33107e9d9ce3b88537d8d44ece0c2f26229/image-20250116-175149.png?cb=e1da80900c88342399ae03f0db3ef5ec) I also updated Sub Test Execution to a Test Execution Record to enable linking and reporting. For each item, I can now set the Edit Link Settings. On one Tab, I set the label I will see from Polarion, for example: ![image-20250116-175440.png](https://docs.sodiuswillert.com/__attachments/a_9d29edefbf69010aad907e440aec87eb5b30c02f1ba0a16b892c99b60971e221/image-20250116-175440.png?cb=54a04b892389621277dde6d465773dd7) On the other tab, I changed the linking behavior from Jira to other tools (limiting the available link types). ![image-20250116-175551.png](https://docs.sodiuswillert.com/__attachments/a_969faad736dc7d40d7d1a2c070772fa4646ca434d51f3ae8e6a061040cfb8fa9/image-20250116-175551.png?cb=350de00d985b2d1fed30dd38af753def) Once I am done, I will have an overview of the configurations for my scheme. ![image-20250116-180150.png](https://docs.sodiuswillert.com/__attachments/a_41e7ed11ac4dd9a382adf2b0ef68ef3a9902aa488ac7720246798cec2ca352f5/image-20250116-180150.png?cb=2accbb83ef4d7fbb78e2513b2cb9e868) *This is an example configuration. Your configuration may be different based on the needs of your organization and processes.* ### Creating Project Associations We must create project associations to link to Polarion from your XRay Tests. On your project settings, look for OSLC Connect Project Associations. ![image-20250116-180458.png](https://docs.sodiuswillert.com/__attachments/a_d0c5e8dadaa3506eeaf777bc23fd9ba60140f1e5655221bc34f8e71c934c5040/image-20250116-180458.png?cb=5851101c5d17f50a4b1e96661df7de17) Add a Polarion project. ![image-20250210-182523.png](https://docs.sodiuswillert.com/__attachments/a_1d0f570fe2ec128ee8491ccfd70c4bf32e9e3d057cbb6a0aad7c45d17c962e96/image-20250210-182523.png?cb=20c269afd79e43e1ef2a9a4a6298a9eb) Now, your Jira project knows what RM projects can be used for linking. ### Linking to Polarion Now, when navigating to a Test, you can start creating Links. In this link dialog, you see many of the configurations you have made. A Test is a "OSLC Test Case" type supporting these relation types. We focused on the Validates Requirement Relationship. From Jira, perform Link → Collaboration Link and select the link type and the remote project. ![image-20250210-182630.png](https://docs.sodiuswillert.com/__attachments/a_770c11b4f9cf77b6a68500f464d1266a50583346b257b7232541b712c65a7464/image-20250210-182630.png?cb=b0ed27acfa0fb6bef16fab6675224887) Users will then be provided the remote selection dialog from Polarion. ![image-20250210-182759.png](https://docs.sodiuswillert.com/__attachments/a_bb81aabaff0ba4c41b4b9d65bfa22ec8ad8fd0c1b50e9e5042b8e1ac2b0c6e99/image-20250210-182759.png?cb=bc470c54d014335d761acceb78718ff4) Note, if you are missing Requirements in the dialogs, you have not configured Polarion to expose requirements as OSLC Requirement Resources. Please review our basic configuration guide for more details → [Siemens Polarion OSLC Configurations](https://docs.sodiuswillert.com/oslc-connect/latest/siemens-tools.md) Once you link, you can see remote content and have link decorators. ![image-20250210-182913.png](https://docs.sodiuswillert.com/__attachments/a_67f469534e6f7d58b96fb9b7175b7ce64d3d1e61f650f6da8205fc2e724b661a/image-20250210-182913.png?cb=5709a6207371d7f02a0e783a6da653ae) Live links from your Xray artifacts to Polarion Requirements! ## Connecting Polarion to Jira XRay To connect Polarion to Jira in most applications, you should follow our guide, which is linked above. However, to add Xray/QM support, follow the steps as outlined below. ### Configuring Polarion for QM Polarion has a significant amount of configurability to support QM. Since it is not a native ability to support QM, some extensions must be performed. #### Update Semantics The admin of Polarion must update the semantics to recognize both the qm domain and the qm to rm relationship types. Three updates need to be made. 1. In the namespace section, add the oslc_qm namespace. 2. In the domains section, add the qm domain and the resource types. 3. In the linking section, add the relationship types. Now, Polarion will understand QM resources. ### Perform your Polarion Mappings Like in the standard configurations for Jira using Change Management links, users need to update their mappings to support the OSLC Link types. Users should update the project or global configuration (depending on the desired scope and commonality) to include a mapping of the link types they wish to use. For example the following mapping would be used if there is a Polarion "validates" link type and these are going to be used to link test cases to requirements artifacts. ### Linking to Jira Once the above configurations are complete, users can link Polarion requirements to Jira Test Cases. On a Polarion Requirement, edit the Linked Work Items and use the "is validated by" link relation. The Globe showing the "Linked Data Friend Server" allows the selection of the Jira dialog. ![image-20250210-184233.png](https://docs.sodiuswillert.com/__attachments/a_9ef337706b8fdd76f1cf814e02586ad02131fd6f37dcdabc81adbe56296ce362/image-20250210-184233.png?cb=735d6468d365e62089250bbc86fec68c) The Selection Dialog will allow you to select the artifact of choice (and ensure it is of the desired project and artifact type). ![image-20250210-184618.png](https://docs.sodiuswillert.com/__attachments/a_5510c5c847eb601c95e43c692fbabb719958b28fdeb045010e2f5f8d9d43bdfa/image-20250210-184618.png?cb=6bacf62eddcf08b742325982ec83d9cb) Or if the Creation is selected, a user can create an Xray Test Case from Jira. ![image-20250210-184744.png](https://docs.sodiuswillert.com/__attachments/a_3348e67ffabe44c77edf7d2bad03d45890c608ed133984f80c7f6121a47a3d37/image-20250210-184744.png?cb=509bf21c6a654e451cf0a57936cd7b9a) ### Advanced Options In Polarion, there will be two advanced options that can be leveraged: Reporting and Tables. Users can customize the Reports to include Test Artifacts with the new Resource Types and Shapes. Users can add Test Data to be visible on a requirement artifact with Tables. An example Report utilizing Xray Test data. ![image-20250210-192308.png](https://docs.sodiuswillert.com/__attachments/a_c470b62afd37f39f146d6a71e3d1ad64a7d60c95c473a70eebe0b25bf1a6c97e/image-20250210-192308.png?cb=effb124f8b2e212bf853962bc7509f37) For example, you can create a new section on your requirement artifact to show the remote artifacts including custom Xray Fields such as TestRunStatus. ![image-20250210-191004.png](https://docs.sodiuswillert.com/__attachments/a_9e300c79fc05cb6ecdadc84d2e953616e7a2830ea86a93f8a50ddf4dcc4735bf/image-20250210-191004.png?cb=5b5b83cc17cbc3c44ce336b8fcaa76f6) --- version: "Working version" language: "en" --- # Failed authentication or authentication loops ## Applies to * Any OSLC application ## Problem User authenticates to the remote application, but the authentication does not appear to be working. While OSLC Connect applications and ELM will enter a login loop, Polarion will display the following: ![image-20211209-104716.png](https://docs.sodiuswillert.com/__attachments/a_5cb74b1223b5c78180475048719ee4e265d410a97b413436fe169d492bbeae02/image-20211209-104716.png?cb=2c885270f4c27fb9ddf8ee9e0f857be3) ## Cause There can be various causes to this. To get a proper root cause, please review the following possible causes: * A popup to authenticate to your OSLC Connect application is closed or blocked The authentication popup can be blocked by your browser. How to determine if Firefox is blocking cookies In Firefox's settings, go to Privacy \& Security \> Permisions. There, you will see ![image-20211215-071159.png](https://docs.sodiuswillert.com/__attachments/a_c701e0ad5327bc2865828660a2228987e6312f635afde5efb71d291085e71553/image-20211215-071159.png?cb=89ef84e5052d7a117224de9e49ac84bb) You will either need to disable this, or add an exception for each of your OSLC applications. How to determine if Chrome is blocking cookies In Chrome's settings, go to Privacy \& Security \> Site Settings \> Pop-ups and redirects. There, you will see ![image-20211215-071626.png](https://docs.sodiuswillert.com/__attachments/a_433fd2ed9aa6001e4dd0c21e61a3434629f25854f1aebac9beec70ff56f42165/image-20211215-071626.png?cb=62264943ffb19b4d492c2e681303e9ee) You will either need to allow Sites to send pop-ups and use redirects by adding each of your OSLC applications to the exceptions list, or enable this for all sites. If the browser popup blocker was enabled and you disabled it, or if there was a plugin acting as a popup-blocker and you disabled it, please try the failing interaction again. * There are blocked cookies in Chrome Cookies are what is used by a given application to store its authentication. If the cookie is blocked, it cannot be used when navigating an OSLC application to interact with another OSLC application. How can I review Chrome's blocked cookies 1. Click on the lock to open the security dropdown menu 2. Click on *Cookies* 3. In the Cookies in use window, click on the Blocked tab If you see blocked cookies when navigating there just after you experienced the authentication problem, you will need to select the cookies, then click `Allow`. Unfortunately, as of now, this procedure has to be performed by all impacted users. * Applications live on different domains As mentioned in the above section, cookies are what is used by a given application to store its authentication. When that authentication needs to be shared by another site, as is needed between an OSLC client and an OSLC server in the OSLC interactions, and if those applications live on different domains, browsers will consider this is a 3rd-party attempting to use a cookie which is not his, and may prevent such usage as a security measure. This will default to a failure in Chrome, and may also break in Firefox if the corresponding security feature has been enabled. How to check if my applications are using the same domain? A simple URL is made as follows: ~(\[\] means optional, and \* means it can be there from 0 to n times)~ `://[.*][.][:][]` If we try to map sample URLs, we would break the domain out as follows: * `https://server.example.com/jira` =\> `example.com` * `https://server.in.a.far.away.sub.domain.example.com:9443/` =\> `example.com` * `https://server.example/confluence` =\> `example` * `https://server/jira` =\> no domain, considered as being de facto different domains **If no**, you may want to review the load balancer configuration, if any. Some OSLC Connect applications are deployed on Atlassian on-premise applications, where the Traffic Distribution feature may have been enabled. Unfortunately, that feature is currently not compatible with our OSLC Connect application. If the problem persists after you checked the load balancer, please reach out to us by creating a support request. **If yes**, proceed with the below. If your OSLC Connect application was already "SameSite=None enabled" at the application server level, that configuration should be removed. Since the release of the Security feature in our OSLC Connect products, we recommend customers to disable any former configuration and rely on that Security feature, which provides better security for OSLC Connect products. If you don't know about that, it is likely not the case. Note that depending on the version of Firefox, this either means that Firefox is not requiring the "samesite=none" property on cookies, or that Chrome is blocking cookies for some reasons. You can use your browser to confirm the cause, as suggested below. Confirming Firefox's configuration You can confirm Firefox's configuration by opening a new tab and entering `about:config`. There you will be able to search for every configuration parameter of Firefox. Search for `laxByDefault`. The first result should be `network.cookie.sameSite.laxByDefault`. ![image-20211213-102237.png](https://docs.sodiuswillert.com/__attachments/a_0e224657fb94c7a5d94ab650962b5d405b3405924085451c3534ab1455cf07b8/image-20211213-102237.png?cb=c6ba29236a020a3205581575ebbfac8b) If the value is `true`, Chrome and Firefox should behave the same. If the value is false, it wouldn't be surprising for Chrome and Firefox to behave differently. Note: for a secured and consistent experience across browsers, we recommend users set this value to true. Confirming Chrome's configuration A user can do a quick determination of the cause by validating the following (using Chrome before version 91, where those settings have unfortunately been removed). 1. Use the Chrome browser after updating flags as outlined below *Navigate to chrome://flags and disable "SameSite by default cookies" and "Cookies without SameSite must be secure". Example in the screenshot below.* ![image-20210113-193212.png](https://docs.sodiuswillert.com/__attachments/a_d078a8f0b7a216058485ded7114d9ed2ff3610566a6914d388eca9402225cb0a/image-20210113-193212.png?cb=7994a2c0eb186476434f36f4a281f12f) Relaunch Chrome and attempt the OSLC behaviors of authentication, linking, and previews. If the behavior works, you will need to see the next section on how to fix it. As a workaround, all users can leverage this capability of Chrome while the resolution is made more permanently. If enabling the above features in an unaffected browser triggers the problem, or vice versa if disabling it in an affected browser resolves the issue, you will find more details about the cause as well as a resolution in [Embedded Content or Authentication Isn't Working between OSLC Applications](https://docs.sodiuswillert.com/oslc-connect/latest/embedded-content-or-authentication-isn-t-working-b.md). If there was no blocked cookies, and you happen to experience the problem, please reach out to us by **creating a support request**. --- version: "Working version" language: "en" --- # FAQ - Migrating to OSLC Connect for Jira Cloud Frequently asked questions for OSLC Connect for Jira Data Center customers planning their migration to Jira Cloud. *** ** * ** *** We know that many of you are existing OSLC Connect for Jira Data Center customers who are concerned about migrating to Jira Cloud. Your OSLC links connect engineering data across Jira, IBM ELM, Siemens Polarion, and they support compliance work that can't tolerate gaps. **Rest assured, the SodiusWillert team is here to support you on your migration journey.**We have assembled a short list of Frequently Asked Questions, to help build your confidence in SodiusWillert and OSLC Connect as part of your Jira Cloud journey. *** ** * ** *** ## **Does SodiusWillert support migrating OSLC Connect data from Jira Data Center to Jira Cloud?** Yes. We are supporting the migration of critical links from Jira Data Center to Jira Cloud. This includes both the update of data in Jira Cloud as well as your Friended OSLC tools such as IBM ELM, and Siemens Polarion. *** ** * ** *** ### **What tools are required to perform this migration?** We are letting the Atlassian Jira Cloud Migration Assistant (JCMA) to handle a significant part of the migration of link data from Data Center to Cloud. SodiusWillert provides additional migration tooling to complete the link redirections and tool-specific updates needed. These are command-line tools that allow you to configure migrations for a single project or for the whole repository. There is a common tool for data migrated from Jira Cloud, and optional tools for each connected OSLC repository. Every environment is a little different. **Please create a support ticket for your migration** (Go to [Support Portal ↗](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/-1)), so we review your specific scenario and advise on each one individually. *** ** * ** *** ### **What are the fees for the migration tools?** We have no intention of charging for the standard migration tooling. We will review your environment and provide the appropriate tools to any existing Data Center customer, at no charge. If you have additional needs beyond a standard migration (rare), or would like priority/premium support during your migration window, we can put together a brief Statement Of Work (SOW) on a case-by-case basis to address your needs. *** ** * ** *** ### **Is the installation for OSLC Connect for Jira Cloud different than Data Center?** Yes. The deployment for OSLC Connect for Jira Cloud involves more steps than the deployment of OSLC Connect for Jira Data Center. Like Data Center, it includes an app from the Atlassian Marketplace (in this case a Forge app), but Jira Cloud's extension model doesn't support the APIs OSLC requires on its own. To bridge that gap, OSLC Connect for Jira Cloud also requires a Broker application, hosted in your own environment. **We recommend reviewing the** [**Installation Guide for OSLC Connect for Jira Cloud**](https://docs.sodiuswillert.com/oslc-connect/latest/installing-and-configuration-oslc-connect-for-jira-cloud.md)**for full details before you begin.** *** ** * ** *** ### **Do my existing licenses also work on Jira Cloud?** Your current OSLC Connect license, obtained through the Atlassian Marketplace, is valid only for your Data Center deployment. To use OSLC Connect for Jira Cloud, you will need a new license from SodiusWillert to enable the Cloud Broker application. You can request on through our [Support Portal ↗](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/-1). *** ** * ** *** ### **Are there any "dual licensing" options that allow a team to migrate incrementally?** Yes. Working directly with SodiusWillert, we can provide a license agreement and license keys that support OSLC Connect on both Jira Data Center and Jira Cloud simultaneously. This is valuable for teams running an incremental migrations. If you'd like to pursue this option, please contact SodiusWillert or raise a support request via our [Support Portal ↗](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/-1) ahead of your upcoming license renewal. *** ** * ** *** **Useful links:** * SodiusWillert [Support Portal ↗](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/-1) * [OSLC Connect for Jira Cloud product documentation ↗](https://help.sodius.cloud/help/nav/0) --- version: "Working version" language: "en" --- # Feature Gaps as compared to Jira Data Center Support We support OSLC Connect on both the Jira Cloud and Jira Data Center. While our OSLC Connect for Jira Cloud is a complete OSLC Solution, some features our customers know and love are not yet available on Jira Cloud. The following features are not currently available in OSLC Connect for Jira Cloud. This will be updated as new releases address these differences in features. Unless otherwise noted, all features are on the existing product roadmap. **Link Type Version Mapping** In OSLC Connect for Jira Data Center, a project could customize whether the Fix Version or Affects Version field is used to set the GC context for a link. The current release supports this configuration in a text file, rather than the UX experience in DC. This will be delivered in the upcoming months. **Type Mapping \& Link Restrictions** As an enterprise feature, we have supported the ability to customer the OSLC usage on Jira types for a Jira Scheme. This meant you could identify which Jira Issue type would be used for a specific ELM use case (for example, Defect). As well you could control the allowable links from that Jira resource type. This will be delivered in the upcoming months. **QM(XRay) Support** In Data Center, we allow the mapping to OSLC QM types. This allowed XRay users to map their XRay Jira items to testing types. This enabled the linking and reporting features natrually availalbe between Xray artfacts and Requirements. In addition we supported shape and QM TRS feeds to enable IBM Report Builder Reporting. This is targeted to be available by the end of the year. **Approvals** A unique feature for IBM DNG is to approve a changeset with a workitem. We allow customizing these rules of what consitutes an approval in our Data Center product. This will be delivered in the upcoming months. **OSLC Query** Our OSLC Query behavior has some limitations in capability in responding to all possible queries. The behavior of this API will continue to be improved. **Resource Shape Customization** Resources shared via OSLC APIs only have standard attributes. We will be adding similar functionality to extend resources to include admin-selected additional attributes. **Friend Rehosting** In Data Center, we had automated the process of retargeting a Friend (Repository connection) to a new location. This is a likely future inclusion. **TRS Participation Check** In Data Center, we allowed an Admin to check is a resource had been added to the TRS feed and when it was last updated. This will be delivered in the upcoming months. **Custom Rich Hover Previews** In Data Center, we allowed users to configure their rich hovers with Jira Screens to customize the content. This feature is under review whether it will be added to Jira Cloud. This information is provided to guide your Jira Cloud migration. If you have specific questions, clarifications, or critical requirements, please create a support ticket so we can provide clarity. --- version: "Working version" language: "en" --- # Friending error codes This page lists the potential errors an admin may experience in OSLC Connect when registering a friend for an OSLC Remote Application. * [\[OCFD-SRV022\] HTTP scheme mismatch](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv022-http-scheme-mismatch.md) * [\[OCFD-SRV023\] Root Services document is already registered](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv023-root-services-document-is-already-regi.md) * [\[OCFD-SRV024\] Local storage for the friend fails](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv024-local-storage-for-the-friend-fails.md) * [\[OCFD-SRV027\] Provisional key generation is not supported](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv027-provisional-key-generation-is-not-supp.md) * [\[OCFD-SRV035\] Document is not a Root Services content](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv035-document-is-not-a-root-services-conten.md) * [\[OCFD-SRV036\] Existing consumer information is invalid](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv036-existing-consumer-information-is-inval.md) * [\[OCFD-SRV043\] Can't connect to host](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv043-cant-connect-to-host.md) * [\[OCFD-SRV058\] Host name cannot be resolved](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv058-host-name-cannot-be-resolved.md) * [\[OCFD-SRV060\] Root Services document not found](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv060-root-services-document-not-found.md) * [\[OCFD-SRV061\] Authentication challenge](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv061-authentication-challenge.md) * [\[OCFD-SRV062\] Access is refused](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv062-access-is-refused.md) * [\[OCFD-SRV063\] Provisional key generation fails](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv063-provisional-key-generation-fails.md) * [No route to host](https://docs.sodiuswillert.com/oslc-connect/latest/no-route-to-host.md) --- version: "Working version" language: "en" --- # Generating OSLC Usage Statistics Ever wanted to see how many OSLC Links your projects have? Did you want to ensure links are only occurring in specific projects? Did you ever want to know how the number of links is evolving? All of these questions can be answered with some simple scripting in Scriptrunner. The attached script is designed to be used to analyze your projects, or to focus on a custom query scope to determine the number of links (and types of links) in your projects. It is a quick and easy way to see your usage profile. ## Running the Script When running the script in the script console, users should expect speedy results. For repositorys with a large volume of links it may take a little bit longer. The output from script is a simple HTML Table with Projects \& Link Type Counts. ![image-20250814-173713.png](https://docs.sodiuswillert.com/__attachments/a_f9ff853ca4c5e14bdbc64dc1296de8e2421ce4e24e2adba17231743cfca568a8/image-20250814-173713.png?cb=862de923c630c7bdc603b61b28d5808f) The Log provides a simple overview of the process. ![image-20250814-174517.png](https://docs.sodiuswillert.com/__attachments/a_02a3fe0f33b49a93ae5aff6863527feb1d96fbddbc03e160fc0176d7896295b3/image-20250814-174517.png?cb=7e4fd1192821eabd3d058930a8df6004) ## Using the output While the table is helpful to review, most users want to retain and analyze these results. For this, we recommend copying and pasting these results into Excel. ![image-20250814-173955.png](https://docs.sodiuswillert.com/__attachments/a_6aa9fe7f4da2b65436e0f540b1d5fbca00fd160e455dcc70300f98951b3864bf/image-20250814-173955.png?cb=495e34d68e776a8a66dbd8ee83ebc446) You can use Excel to do some calculations and sorting. You can also store historical outputs to use in analysis and graphs over time (and import into Python scripts). ## The Script The script is available for usage however you see fit. You can also modify it to extract additional data from the links ([Understanding OSLC Connect for Jira Link Storage](https://docs.sodiuswillert.com/oslc-connect/latest/understanding-oslc-connect-for-jira-link-storage.md) ) to suit your needs better. This is a simple example of the data that can be easily accessed with Scriptrunner. [oslcStatsFinal.groovy](https://docs.sodiuswillert.com/__attachments/a_eabef618d0b542a6beeea1cd045ae7e4261c89537290180e9fc7d56608bf73c2/oslcStatsFinal.groovy.md?cb=009163081eabd14d39f20438a81dd9d1) Note our usage of the linkedissueofremote filter in the JQL. Without this filter our queries take much longer to complete. This helps us return only Jira Issues with OSLC Links. --- version: "Working version" language: "en" --- # Get started Our knowledge base is split into two types of articles. How-to articles are meant to educate on the specifics of OSLC and the usage of the products. Those can exist as simple articles, but some are developed in our Learning Journeys. Troubleshooting articles, on the other hand, are there to help you resolve specific problems based on an observed symptom. The simplest way to find the content you need is to use the search bar If you need more assistance, you can e-mail our support dest at [cusoslcjra@sodiuswillert.atlassian.net](mailto:cusoslcjra@sodiuswillert.atlassian.net). To make it easier for users to create detailed support requests, we have created a short simple guide that you should take a look at, just in case. [Help us help you: on creating good Support Requests, reporting even better on Bugs, and suggesting awesome New Features](https://docs.sodiuswillert.com/oslc-connect/latest/help-us-help-you-on-creating-good-support-requests.md). ## Learning Journeys * [OSLC Connect for Jira Cloud](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira-cloud.md) * [OSLC Connect for Jira Data Center](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-jira.md) * [OSLC Connect for Confluence Data Center](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-confluence.md) * [OSLC Connect for Windchill](https://docs.sodiuswillert.com/oslc-connect/latest/oslc-connect-for-windchill.md) ## Frequently asked questions * [Failed authentication or authentication loops](https://docs.sodiuswillert.com/oslc-connect/latest/failed-authentication-or-authentication-loops.md) * [Rich Previews/Dialogs not visible?](https://docs.sodiuswillert.com/oslc-connect/latest/rich-previews-dialogs-not-visible.md) * [Can't add datasources from Rootservices? Setting the protocol for outbound ELM requests](https://docs.sodiuswillert.com/oslc-connect/latest/can-t-add-datasources-from-rootservices-setting-th.md) * [Polarion OSLC Services for your Configuration](https://docs.sodiuswillert.com/oslc-connect/latest/polarion-oslc-services-for-your-configuration.md) * [Planning your Polarion Mappings to Jira (via OSLC)](https://docs.sodiuswillert.com/oslc-connect/latest/planning-your-polarion-mappings-to-jira-via-oslc.md) * [Using OSLC Tables in Polarion Forms](https://docs.sodiuswillert.com/oslc-connect/latest/using-oslc-tables-in-polarion-forms.md) * [Using Global Configurations With Jira](https://docs.sodiuswillert.com/oslc-connect/latest/using-configurations-with-jira.md) * [Debugging errors using the browser developer tools](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-the-browser-developer-tools.md) * [Debugging errors using Jazz / CLM / ELM log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jazz-clm-elm-log-files.md) * [Debugging errors using Jira logs](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jira-logs.md) * [Debugging errors using Polarion log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-polarion-log-files.md) --- version: "Working version" language: "en" --- # Getting Started with OSLC Connect for Jira Cloud Videos coming soon! --- version: "Working version" language: "en" --- # Help us help you: on creating good Support Requests, reporting even better on Bugs, and suggesting awesome New Features Explaining what we are going through or expect as a user is almost an art. Determining what is the relevant information to share, and what is not, can be a daunting task. To avoid the frustration of being asked for information on your problem when you are not in front of it anymore, we have created this article which draws out the major items we hope to find in your requests. ## Creating a Support Request To start with: a support request is about asking for help about behavior you don't understand, a feature that feels off, something you wish you had, but you don't know where to start. First, you need to set the context: * mention the applications you are using * add their version if you have that information. Then describe: * the situation you are facing and * the question you have with regard to that. In some cases, you may additionally: * check the [Debugging errors using the browser developer tools](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-the-browser-developer-tools.md), and either: * review any outstanding message in the console as well as anything particular in the network view and share screenshots of those if possible, or * provide us with the HAR file of the interaction if this is something you can share * provide logs of the behavior: the articles [Debugging errors using Jira logs](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jira-logs.md), [Debugging errors using Jazz / CLM / ELM log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jazz-clm-elm-log-files.md) , and [Debugging errors using Polarion log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-polarion-log-files.md) are full of useful information in that regard. Now that you know what you need, head off to [create a Support Request](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/52/create/257). ## Creating a Bug A bug is meant to describe a behavior that you expected to be different. You would typically share: * the applications you are using * it's version if you have that information. Then describe: * the behavior you observed * the behavior you expected You should additionally: * check the [Debugging errors using the browser developer tools](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-the-browser-developer-tools.md), and either: * review any outstanding message in the console as well as anything particular in the network view and share screenshots of those if possible, or * provide us with the HAR file of the interaction if this is something you can share * provide logs of the behavior: the articles [Debugging errors using Jira logs](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jira-logs.md), [Debugging errors using Jazz / CLM / ELM log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jazz-clm-elm-log-files.md) , and [Debugging errors using Polarion log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-polarion-log-files.md) are full of useful information in that regard. Now that you know what you require, head off to [create a Bug](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/52/create/256). ## Creating a New Feature A new feature should detail a new behavior, or the evolution of existing behavior. To clarify your intention, you should always: * detail the existing behavior: this will help us confirm that the behavior is understood as we meant it in the first place * explain why you consider this should be changed, * detail the update you suggest. Now that you know what you require, head off to [create a New Feature](https://sodiuswillert.atlassian.net/servicedesk/customer/portal/39/group/52/create/258). --- version: "Working version" language: "en" --- # HttpUnauthorizedException in LDX or LQE ## Applies to * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem When trying to add a data source in LDX, an HttpUnauthorizedException error happens when you test the connection with the message `oauth_problem=consumer_key_unknown`. ![Screenshot 2022-01-04 150538-20220104-140540.png](https://docs.sodiuswillert.com/__attachments/a_275929f16d8ecad7f238639d297e7f1ebc34932d07ef8736166320f7702435f8/Screenshot%202022-01-04%20150538-20220104-140540.png?cb=bf340808a02b85bf21dae7a23357ab2f) ## Cause The consumer key used in the data source properties is most likely incorrect. ## Resolution Create the consumer key in the remote application before adding the data source. Once this is done, make sure to use the correct consumer key when adding the data source. ### **Related documentation** * * --- version: "Working version" language: "en" --- # IBM specific articles This section contains troubleshooting information related to IBM Engineering Lifecycle Management. * [Issues using OSLC Connect with ReportBuilder](https://docs.sodiuswillert.com/oslc-connect/latest/issues-using-oslc-connect-with-reportbuilder.md) * [Can't add datasources from Rootservices? Setting the protocol for outbound ELM requests](https://docs.sodiuswillert.com/oslc-connect/latest/can-t-add-datasources-from-rootservices-setting-th.md) * [Resolving Issues Connecting to DOORS Classic](https://docs.sodiuswillert.com/oslc-connect/latest/resolving-issues-connecting-to-doors-classic.md) * [Debugging errors using Jazz / CLM / ELM log files](https://docs.sodiuswillert.com/oslc-connect/latest/debugging-errors-using-jazz-clm-elm-log-files.md) --- version: "Working version" language: "en" --- # IBM Support Questions --- version: "Working version" language: "en" --- # Installation and Configuration Troubleshooting Installation of the OSLC Connect for Jira solution requires installation on from the Atlassian Marketplace and a Broker application locally in your environment to connect. Installation guides are available in our online help, to guide you through the process. You can get to the help → Note, the Docker install option is just for trial deployments. We recommend review of the installation and configuration guides before installation. If you have any questions, please contact our helpdesk @ cusoslcjra@sodiuswillert.atlassian.net. --- version: "Working version" language: "en" --- # Installing and Configuration OSLC Connect for Jira Cloud --- version: "Working version" language: "en" --- # Issues Linking with Polarion Issues using OSLC Links from Polarion are related to three common issues. ## Turn on External Linking It is mandatory for OSLC linking to enable external linking. If it is not enabled, the external link icon will not be activated and you will be unable to initiate linking from Polarion. The configuration is a repository default, and a project specific configuration. You can find the configuration by navigating to the Linking Configuration in WorkItems. ![image-20210125-160254.png](https://docs.sodiuswillert.com/__attachments/a_d3a504f90ccf17f1a11648c4ddc16beb57a2ed5c7d1789f3130acef208e45d0c/image-20210125-160254.png?cb=17e4aafffc824e0b3ae88979144e1483) Then ensure that External Linking is Enabled ![image-20210125-160334.png](https://docs.sodiuswillert.com/__attachments/a_5008c200e5f73efcea39ff4af1f0b345f476ee77aef69ea138f18f1e65a98b0e/image-20210125-160334.png?cb=1e34b2ba948138c0f3a6d83dbf46b5bf) Linking on mapped link types should now be available. Typically this will be link types such as "related to". ## Address Missing Project Associations If after turning on external links, there is no option for an external link (not even a shadow icon), this is an indication that Polarion does not believe there should be external links. You should review the following. 1. Polarion must be Friended to at least one other OSLC Application 2. Your Polarion project has a project association to one of the Friended applications ## Address the OSLC Configuration If linking is still not available, you will need to check the OSLC Mapping configuration which controls the types and the links that are used by OSLC interfaces. This will be evident if you are looking for links from Polarion and cannot get the third icon (globe) to be available when creating links believed to be OSLC enabled. For example this would look like the following: ![image-20210125-160638.png](https://docs.sodiuswillert.com/__attachments/a_b6b00a04a7f85ed915f7be198831617aa851fc6826f55eca8c3779a6afa25be2/image-20210125-160638.png?cb=4d589286a1bb3cfa2310b194e2a70e44) Also if you are attempting to create links from Jira to Polarion and observe an error like the following: ![image-20210125-160756.png](https://docs.sodiuswillert.com/__attachments/a_6b101616c844e05532a647ca942c9e7407f29c1c213d93e68546a3e0047bd1d5/image-20210125-160756.png?cb=d6cf7f1f0a22565ce6b5d39229aa8b57) Would indicate that Polarion is unaware of any types that are enabled as OSLC artifacts and does not allow any links. If you have either of these issues please see the knowledge base article --- version: "Working version" language: "en" --- # Issues using OSLC Connect with ReportBuilder Including OSLC Connect data in ReportBuilder or Engineering Insights (RELM) requires the consumption and visibility of OSLC data from the source OSLC Connect tool and processing by LQE. The following document enables you to review and resolve your issues in having your contents available for reporting. Note, since Engineering Insights leverages the same data sources as Report Builder, in most cases, the resolutions are the same and solved at the same time. The types of errors we are addressing. * Missing Projects or Elements in Reportable Resources * No update of artifacts * The inability to see OSLC Connect shapes in Reporting * The inability for some users to see OSLC Connect Artifacts in Reports * Rich previews in reporting applications The examples below show OSLC Connect for Jira examples, but other OSLC Connect applications have the same basic behaviors. ## Checking your Data Source (TRS Source) The OSLC Connect resources in any reports depend on the feed coming from the OSLC Connect application. ### Check that a Functional User is Assigned The TRS feed creation depends on a functional user who has access to see the artifacts in the OSLC Connect source application. If the user assigned to the data source does not have access to artifacts, they will not be included in the report. In the OSLC Connect Administration, you should be reviewing the assigned Functional User. ![image-20210223-201319.png](https://docs.sodiuswillert.com/__attachments/a_39a2cb356cad2441a476fd12b6d64adce85589d62ad7d26c0c00a2b128f87239/image-20210223-201319.png?cb=b25c72de2c76d13ed6df432e351f0117) This user is often a service account or a Jira admin account to give permission to all the artifacts. ### Check the project access of the Functional User We do provide a simple guide to what projects are included in the TRS feed. ![image-20210223-201551.png](https://docs.sodiuswillert.com/__attachments/a_b866ffb7b00347ab15ceb0be27e8ab9822c95240cc08380d33c341a4251245ad/image-20210223-201551.png?cb=a7626b7db590632945c72a22fe4796c5) This will be a hint if the user has access to the artifacts necessary to perform the reporting. If you change the TRS Functional User, you will need to re-build the TRS Resources (action enabled on the right of the above view), and in LQE, you will be forced to rebuild (see Check the status of the Jira Data Sources). Also note, that our application will not include a project until an OSLC link exists to make sure we manage the scale of artifacts exposed to LQE. ### Check the LQE Consumer has the Functional User assigned A final step is to make sure your LQE consumer has the functional user assigned. Without it, your LQE request for the TRS will fail. Your LQE consumer in OSLC Connect should look similar to the following: ![image-20210223-202138.png](https://docs.sodiuswillert.com/__attachments/a_f18aa7406bdd9b677c2755c79c08acda1f3a5ecc62b5c73c49fc4fc39005a7d0/image-20210223-202138.png?cb=1078cef128f2a6a2931c4cb931f784e9) ![image-20210223-202101.png](https://docs.sodiuswillert.com/__attachments/a_d961df2efe0aa11ac08f1620eedb41a2c692b21ab5689f556f39f27b1afcc08d/image-20210223-202101.png?cb=2300c8bcf6fff35b430493a125155677) If there is no consumer assigned, use the actions to assign the consumer. ## Checking Receiving TRS Data Source Once it has been determined that OSLC Connect provides a correct TRS feed and has the Functional User assigned, we must be assured that the data source is being read correctly in LQE. ### Check for Jira Data Sources Navigate to the LQE Admin page to check for data sources. It should be something similar to '[https://myjazzserver/lqe/web/admin/data-sources'](#). If you have questions, it should be in your jazz application drop-down. ![image-20210223-202750.png](https://docs.sodiuswillert.com/__attachments/a_0565480e423b13090745255c237cfe97757f6b9f8ad2eacb02f4028647bff32f/image-20210223-202750.png?cb=ff2949041827bb04fb2d0ec3daa807f9) In the administration, we are looking for the Data Sources to make sure Jira is being read. We should see two data sources (on 'cm' and one 'process'). Their names may vary, but they will look similar to the following, and their URLs should be relative to your Jira Server. ![image-20210223-202951.png](https://docs.sodiuswillert.com/__attachments/a_c49a4efe0074d3ff0cc145c50e105858ca3bc62071c37661966fa1206e335489/image-20210223-202951.png?cb=1ef7e4c6071421cc7f186293b679d228) If these are not available, please reference the installation guide for making these connections. ### Check the status of the Jira Data Sources If you are missing data or missing data updates, the issue can be that the TRS feed has had issues reading the source. You are looking for the status next to the feed that should look like the following: ![image-20210223-203242.png](https://docs.sodiuswillert.com/__attachments/a_8cdf3e4b999279494ce78ed9068ed9ddbfcfc19064eb692dbd5168e330734b87/image-20210223-203242.png?cb=fa2b33f3751b576dbceeb0a88461c2e7) A green check means the feed is up to date, and there are no issues. An error indicates a resolution is in order. The issue will look similar to the following instead of the green checkmark. ![image-20210223-203445.png](https://docs.sodiuswillert.com/__attachments/a_59cbc52a8d5a60562e6b571bf080e1a51e2c9fb8b63c83b200f5187f90cb813e/image-20210223-203445.png?cb=f998fabadc64559bc2a861298db28e30) #### Normal Resolutions To resolve the issue, you will want to review the actions. Two standard issues are easily resolved. Simple rebuild issue. For some reason, the TRS feed has had an issue. This could be due to a functional user change or an interruption in your Jira server's service. In either case, rebuilding the index should address the issue. Oauth Authentication issue. Either a user in LQE or in OSLC Connect changed the key or secret for the OSLC Connect consumer connection. Either update the key again or re-perform the connection with OSLC connect as guided in the installation guide. ### Check the permissions of Jira Data Sources LQE provides a permission model on who can access the data contents included in a report. This is used to ensure that your accessibility model is being followed. This should be reviewed so that both your security policy and expectations are being addressed. If the permissions are too strict, users will not be able to report on the Jira data. To review, navigate to the permissions in LQE. ![image-20210223-204554.png](https://docs.sodiuswillert.com/__attachments/a_f281705fc6ab3425eeed90e3f85452b54941233d2c0d50e2ff9e3a18d783de13/image-20210223-204554.png?cb=596a124ffb5b9b84ff1c1f3a5e168bab) In the permissions, these are organized by the process project groupings. ![image-20210223-204649.png](https://docs.sodiuswillert.com/__attachments/a_45208dd394c54515a90be54ac83597aa333d25e99c9437c470a4355b402769c3/image-20210223-204649.png?cb=0d53d6a3618c21f76df70936196897f5) These permissions are set hierarchically, and you can control these by specific groups or individuals. For example, the following is a default (and very permissive) setting using the Everyone group. ![image-20210223-204822.png](https://docs.sodiuswillert.com/__attachments/a_d36ac45b98371f5076625ec876b68bc5a5bdf1a10e0ed6a258f099ea25fbe17f/image-20210223-204822.png?cb=99ac2bcdc044ed4a616c77fa86ac7a14) You have the flexibility to set this how you wish, but it can cause restrictions in the user access to data. Once these steps are completed, LQE will have OSLC Connect data and can be accessible by the reporting tools. ### (Unlikely) SPARQL Check Some users may want to see information to show the data in LQE. You can do a check with a SPARQL Query. If you know SPARQL, you can write a simple query. Also, an example below is a query of all my Jira artifacts implemented by links. Note, be cautious with SPARQL queries because they can consume significant resources. This step should be pursued only after the following report checks have inconclusive results. Note that the Jira server prefix is being used to filter only links to your specific Jira repository. PREFIX oslc_cm: PREFIX dc: PREFIX rdf: PREFIX oslc: SELECT ?changeRequest ?implementedRequirement WHERE { ?x oslc:shortTitle ?changeRequest . ?x oslc_cm:implementsRequirement ?implementedRequirement . ?x oslc:serviceProvider ?serviceProvider filter contains (str(?serviceProvider), "https://myJiraURLprefix/") } ## Checking Report Builder and Reports When we are working with ReportBuilder, we are focused on two elements. The first is that Report Builder is not providing OSLC Connect artifacts for Reporting. The second is that my report does not contain the OSLC Connect artifacts you expect. ### Checking Reports When configured correctly, creating a report will naturally offer Jira (or Windchill) artifacts for performing reports. When correctly configured, a user should see these artifacts as selectable options. ![image-20210223-210217.png](https://docs.sodiuswillert.com/__attachments/a_cd86439c43a30e57a1c123e39b967b1738f892af6827b813066e86a088cacfa3/image-20210223-210217.png?cb=7b9faa1f1968c6d378cc7a83c14ac3d0) If these options aren't available, please check the following elements. #### Check the Report Type Go to the top of the report definition and look at the Data Source. ![image-20210223-210431.png](https://docs.sodiuswillert.com/__attachments/a_c3e8e64e8b1dad47f3fbe1b2d6402ded705708d004c13867643d916e710df1d3/image-20210223-210431.png?cb=37604846dcbc5b6e7f8bd80c2f8308a5) If the data source is not an LQE based data source (such as Data Warehouse), it will not work. You cannot use the Data Warehouse with OSLC Connect. #### Check the Scope Report Builder attempts to be 'smart' and filter out selections that are not applicable. For example, if I pick only an EWM project for my scope. ![image-20210223-210650.png](https://docs.sodiuswillert.com/__attachments/a_9d8821206fcacc9b019fb0d806b685ab03779d40b711072de9495db8b26777b4/image-20210223-210650.png?cb=a26957cd417a6064762fa1a57fdd654e) My allowable artifacts will be scoped accordingly. ![image-20210223-210750.png](https://docs.sodiuswillert.com/__attachments/a_0f2f6e2c0440e0d3ad8efd2c6e968376cbc82fa08e50bb79ebc546b9a835fed9/image-20210223-210750.png?cb=3c451d093eb5301a66c7540a2c6dd435) Make sure you have selected your OSLC Connect products in the scope of your intended report. ***IMPORTANT: ReportBuilder uses Jazz Abbreviations for Project Scopes no matter the data source. Your Jira projects will have a - CCM Project Area even though they are from Jira. For example, a Jira project named 'JIRA TEST' will show up as follows:*** ![image-20210223-211056.png](https://docs.sodiuswillert.com/__attachments/a_063b07c3240a86f743a9dee998415a9984b63f63cdf149238d05a33cf87820cb/image-20210223-211056.png?cb=635a0a5dacb14fb3a8b83a65a0064f3f) Scope issues are the most common reason for missing OSLC Content in Reports. ### OSLC Artifacts are Not Available If the above actions do not allow Jira artifacts' selection, it is most likely that the ReportBuilder endpoint has not been refreshed yet. As a general rule, ReportBuilder refreshes daily to identify new shapes and projects (a great resource for more detail can be found here → ) A simple solution is to 'refresh' the LQE endpoints. You can review endpoints in your report builder by navigating to the data sources or see them all @ ![image-20210223-212803.png](https://docs.sodiuswillert.com/__attachments/a_a593bc35e088cf81cfafeb39b1a0aae7fa7c54476592a79354e0ef98b927673b/image-20210223-212803.png?cb=eaacdbf8efe24dc5e89bb7351a3f09b5) Navigate to each LQE based Datasource and perform a Refresh. ![image-20210223-212840.png](https://docs.sodiuswillert.com/__attachments/a_6916de102ea5b13549a1d6a81994598e2d63cb6366f315d5df1e3dc4b34dc8ee/image-20210223-212840.png?cb=5a856bfc0b62bb8d9f6d61b35f013fcc) Note you will be able to see the last refresh date at the bottom of the data source to give you more information on when the activity last took place. This activity can take several minutes on each source. Alternatively, the next day, you most likely have been refreshed automatically. ### OSLC Attributes Not Available Some of our OSLC Connect products allow the customization of the attributes that are included in the shapes. If you make a change in the attributes available you will need to make a meta-model refresh the same as the previous section. ## Report Content Issues Our last challenge once our data sources are properly read is building good reports. Building good reports is difficult, but once we have validated the data sources are good, we encourage good practices in debugging these complex reports. ### Start Simple While the report builder is immensely powerful, we recommend building incrementally to assure that the complex relationships you are reporting on are building as expected. ### Configurations are Complex Reporting with Configurations can be rather complex. We recommend working with some simple data sets (including configurations) to validate your logic and configuration reports. ## Rich Hovers ReportBuilder and Engineering Insights both offer rich hovers to locally embedded artifacts in the Jazz platform. With RB, the OSLC Connect products do not currently support rich hovers. The rich hovers for the Jazz tools assume specific authentication behavior, so you should not be concerned about no rich hovers on the Jira artifacts. With ENI, the OSLC Connect product does support rich hovers. To enable this, please go to the Admin of the application and create a Friend with your OSLC Connect product to enable the rich hovers. --- version: "Working version" language: "en" --- # Log4j 2021 vulnerabilities ## Products * OSLC Connect for Jira * OSLC Connect for Confluence ## Related CVE * CVE-2021-44228 * CVE-2021-45046 * CVE-2021-45105 * CVE-2021-44832 ## Disclaimer OSLC Connect for Jira does not ship Log4j. We rely on the Log4j provided by Atlassian in Jira. Atlassian [confirmed they suffer a very limited impact](https://confluence.atlassian.com/kb/faq-for-cve-2021-44228-1103069406.html), since they bundle Log4j 1.2. from both CVE-2021-44228 and CVE-2021-45046. Steps to confirm and mitigate should be applied from the above mentioned article. Last, and as mentioned on the Log4j website for [CVE-2021-45105](https://logging.apache.org/log4j/2.x/security.html#CVE-2021-44832) as well as [CVE-2021-44832](https://logging.apache.org/log4j/2.x/security.html#CVE-2021-44832), these are not affecting the 1.x branch of Log4j. --- version: "Working version" language: "en" --- # Maintaining the Health of your OSLC Connect Solution Managing and maintaining an OSLC Solution is critical for the user experience in the enterprise. Since we embed critical functionality in remote tools, the up-time, availability of these solutions are critical to may tools within your enterprise. Following are suggested health and management practices to engage in for your system's overall health. ## Management of your IT infrastructure OSLC uses web technologies to connect and integrate your engineering tools. This means that there are many services being used and leveraged in your integrated enterprise. When you did your original installation there are often some tweaks needed to be done to address your IT connectivity. It also makes sense that the administrators maintain awareness of the enterprise for changes post installation. The following are the types of changes that should be monitored as they can disrupt performance. Servers - Name changes are the most critical. OSLC uses linked data, meaning your artifact URLs (including server name) are embedded in your links across repository. While some tools provide support for name changes, they do create disruptions and plans should be made to manage these impacts. When connecting servers across domains, we often need to address samesite constraints that enable usage of embedded content. This can affect header configurations in the servers, so at any time that these configurations are modified they must be re-tested. Firewalls - The connectivity between servers is critical. We have observes firewall to limit connectivity or modify header contents to disable server to server connectivity. If a new firewall is to be added, take care that connectivity remains between your OSLC environments. Load Balancers/Reverse Proxies -- These are common appliances that are often placed in front of a cluster of application servers. They can provide significant value in keeping server addressable names consistent, but the configured behaviors can cause issues. Most often activities such as node affinity (session stickiness) should be addressed, as well as changes in traffic shaping can impact behavior observed by users. Most notably in the later two is inconsistent session authentication behavior. ## Caring for your license and updates Your OSLC Connect for Jira is an annual subscription and includes regular updates through the Atlassian Marketplace. The admin should be aware of the Application's license status. This can be viewed in either Manage Apps -\> ![image-20240228-200247.png](https://docs.sodiuswillert.com/__attachments/a_42f49b7bff92ea1ab5a3f56f699550899c0fbbfbc3f3ba74248100045974225d/image-20240228-200247.png?cb=1473a4b725438a17456e96991d18899c) Or the OSLC Connect for Jira Status Page (https://myjiraserver/plugins/servlet/oslc/status) ![image-20240228-200329.png](https://docs.sodiuswillert.com/__attachments/a_ff7925b4c8d1ca4c4a15a624a0da03c8cbee4cd1f57fc9f783d6f3bb615d7211/image-20240228-200329.png?cb=3abfffb178f93866ad221bca9311ddd3) If there is an issue look to address it quickly. Note that in Managed Apps you will see the expiration date of your license. It is common when doing a product renewal to align these dates to a common renewal date for your team to manage your Jira plugins consistently. We definitely support this. ### Product updates If your product is connected to the internet you will have a notification decorator showing that an update is available whenever we release a new product. ![image-20240228-201152.png](https://docs.sodiuswillert.com/__attachments/a_9f25ed170d54df7c48cd1f50857d5e2780904dbdbb860ff22f9af5e1d3d11f07/image-20240228-201152.png?cb=8da3be990e3a1cc2a1942b95d0765736) We generally recommend updates, but we also suggest that you review the release notes and check compatibility with your Jira version. Those not connected to the marketplace can manually check for versions and download from → [https://marketplace.atlassian.com/apps/1221984/sodiuswillert-oslc-connect-for-jira?tab=versions\&hosting=datacenter](https://marketplace.atlassian.com/apps/1221984/sodiuswillert-oslc-connect-for-jira?tab=versions&hosting=datacenter) ### Caring for plugin up-time We recommend that there are some standard checks on when to check for operation of the plugin. It is common to check for the status of the plugin on the completion of a server restart. We also recommend on checking the status of the plugin on the disabling or uninstalling Configuration Manager for Jira (CMJ). We recommend this as we do support this plugin and Jira's plugin manager tends to be aggressive and disable our plugin on uninstallation of CMJ. To resolve, simply disable and then re-enable our plugin. ## Caring for Friends and Consumers Friends and Consumers are the connections between different repositories. It is important that these connections are maintained and valid. Issues with your connections can help you get ahead of user issues. For managing Friends, us the Friends Page. ![image-20240229-142717.png](https://docs.sodiuswillert.com/__attachments/a_c1a55bd7f8994f4df3a929a5649c6d5730b6f5d46ae7415c2ebc7e301e3630fc/image-20240229-142717.png?cb=fe113068d87e9bbd3271427a1637d684) The "Refresh" button will go check the status of each of the Friends. It will check for availability of the remote server, existence of the key, correct storage of the secret, and the current approval status. It can help you track down issues quickly. For consumers, it is required to check these from the remote servers to confirm status. ## Caring for Tracked Resource Sets Tracked resource sets provide the ability to allow tools to monitor for change and index resources. It is especially important for the IBM ELM suite as it relies on the reading of TRS for identifing the artifacts to be indexed and changes that force a re-read of an artifact. Checking the health of this services is critical. The main page of interest is at . A few things to look for on this page are: The TRS Functional User. This is the user that has access to the projects to report on the artifacts and changes of artifacts. We recommend that this is a Jira Administator. The reason is that using any user permissions other than this can result in missed projects or missed artifacts. Since this role is used in a read-only mode, there is no issue in using an Admin. We provide support to identify what projects are included in the TRS feed. This is constrained by the Functional User as well as those projects that are OSLC Enabled (defined by having OSLC Project Associations). We provide statistics to show what projects are enabled and the functional user has access. ![image-20240229-183947.png](https://docs.sodiuswillert.com/__attachments/a_8ab6b139625a6a112f2f7d1d754b67989d444e44dfafd09718501f05f6386dc0/image-20240229-183947.png?cb=d64b4bb6e679c13dbf442f9b1886fa89) Search through the list to determine which projects may be absent due to access issues by the functional user or missing project associations. The feeds will give you metrics and status on the number of artifacts in each feed. ![image-20240229-184128.png](https://docs.sodiuswillert.com/__attachments/a_7cf9aedea631e6c7781a0510f4683a534d209dcc6ffeb7de261ca1ebd3898746/image-20240229-184128.png?cb=2f4a46501113f4291bbf8b260fb4f75f) As a general rule the Process resources should be 1 more than the number of OSLC Enabled Projects. The Change Management artifacts will total the number of Jira issues in the OSLC Enabled Projects. If we detect an issue with the feed we will recommend a rebuild. ![image-20240229-184651.png](https://docs.sodiuswillert.com/__attachments/a_b61ed92faa23aff127fbebc85388beb86da98a50ba883524b53e8011ba873df4/image-20240229-184651.png?cb=428e06355b46cb4572591ceab5c1dd9a) A rebuild will force the recreation of the TRS feed. And will required all users of that TRS feed to reindex. In practice the local rebuild is quick. The remote index usually takes significant more time so be cautious performing extra rebuild/reindexes. When rebuilding you will see the following. ![image-20240229-184918.png](https://docs.sodiuswillert.com/__attachments/a_dcf9808aa1720fc46af1a9d6b2adcaafa364791615c0cadf537a09f3007ec0e2/image-20240229-184918.png?cb=64cba347cbcc0358535e104a690f7304) Once complete you can request a reindex in the consuming applications. It is strongly recommended that the consumer of the TRS feed is using the same functional user as the TRS Functional User. If not we show this warning. ![image-20240229-185053.png](https://docs.sodiuswillert.com/__attachments/a_3c1580552567256502a8e272947665393b5ebf089e67424f19b0b35c1e4395c7/image-20240229-185053.png?cb=2eca3346f7e6918be732da97445f24ac) The reason we recommend this is we want the same permissions to build the feed as to read the feed so no artifacts are inaccessible. Look to the consumer page to edit. ![image-20240229-185245.png](https://docs.sodiuswillert.com/__attachments/a_5b20271c8687b96974ec596c8804f59204c537b8339948c4c96ee0719c934133/image-20240229-185245.png?cb=e157998c175056749397ea9c6c5e7165) ## Caring for consumers of TRS (IBM LDX \& LQE) While our solution generate the tracked resource sets and provides the artifacts, there should be review of the uses of these Tracked Resource Sets. In IBM ELM, this means LDX (Link Index Service) and LQE (Link Query Service). In practice LDX provides for link discovery service (showing Jira links in DNG and ETM) and LQE provides reporting services (showing Jira issues in Report Builder). There are more configurations you can do and you should review our videos on these but these are the basic health checks you should be doing. ### Ensure the right Data Sources In the Admin of LDX and LQE review the data sources. You should have: * One data source in LDX (CM Resources) ![image-20240229-185857.png](https://docs.sodiuswillert.com/__attachments/a_f5f3d5956a9e9a19b571c524aad45b0a7994e8c23e1874567c321353ed9ee6db/image-20240229-185857.png?cb=4e45da4dc3f8c62a1d92276508b6677a) * Two data sources in LQE (Process and CM Resources) ![image-20240229-185947.png](https://docs.sodiuswillert.com/__attachments/a_9b3a1ae06effaaf65b3fd21d0ea3487a2103aff61bf5b126539defa5f5ed1d16/image-20240229-185947.png?cb=af722c68db6a7e83c74a799092e9ba28) ### Ensure the Data Sources are in a Green State For up to date link discovery or reports, the indexes must remain up to date. The IBM indexes will hault indexing if they see unexpected changes from previous requests. These are usually related to a TRS rebuild event, or some Jira maintenance/restoration event that was inconsistent from the IBM indexes. You can review the data source in LDX and LQE for status and a recommended action. ![image-20240229-190917.png](https://docs.sodiuswillert.com/__attachments/a_c408e4b6ed91b6b9a836b06496128665ef3b655647aa411bdf9d6b935a29a6e0/image-20240229-190917.png?cb=1e68585420ba6c87559574c449e82983) In this case the truncated change log was due to a rebuild event in Jira. Simply Reindex the data source and normal operation will return. Depending on the size of the TRS feed it could take minutes or hours. To provide a context of actions, the TRS feed is simply relating the items that must be indexed or re-read after they changed. The index reads this TRS feed and then retrives data on each of those artifact from Jira so it can be a extended activity. If you see a 429 error (too many requests) this indicates that rate limiting has been activated on your Jira server and limiting the requests for resources. If this is the case, the resolution must occur in Jira to create an exclusion for rate limiting. Often you can use the Oauth consumer key for LDX/LQE to create this exception. Note, you can use the Data Source Notifications to warn about issues in the Data Sources so they aren't a surprise. If you have questions on the contents of an index and want to investigate a specific Jira issue, use one of our discovery queries in the Sparql interface to help identify the issue. Repeated re-indexes are probbaluy only going to slow the environment and not resolve the issue. ## Management of Jira performance Operations for OSLC Connect for Jira are mostly small REST services with little load on the Jira environment. This is both in performance testing we do with Atlassian as well as in practice. This means that there is little additional resources dedicated specifically to OSLC Connect. Normal monitoring of Data Center nodes is sufficient to address loading and additional resources when necessary. But we have not seen additional loading strictly with OSLC Connect. The largest load that we see in the Jira environment is when using IBM and performing a re-index. This will have the IBM Servers read every Jira ticket. For this reason we recommend users limit the times that they do a reindex to error situations. ## Metrics on Jira OSLC Usage Some organizations want to gather metrics on usage of OSLC Connect. We would related the following types of metrics that would provide value. **Simple metrics** The following metrics can be found on Admin pages * Connected Repositories (Friend/Consumer Screens) * Number of OSLC Enabled Projects (Tracked Resource Set) * Number of OSLC reporting Jira Issues (Tracked Resource Set - CM Resources) **Possible Link Metrics** If desired to count the number of OSLC links stored in Jira you can use the information that these links are * Jira Remote Links * Their type is "com.sodius.oslc.app.jira" **Activity Metrics** Creating user activity metrics would be difficult as it would require monitoring of user traffic both inbound and outbound. We believe the static scale number of Jira issues give a sense of usage. If you want daily links created, you would need to create a script to detect the artifacts updated in the last 24 hours, review the changes for remote links, and count the number of remote links of type "com.sodius.oslc.app.jira" ## -- Requests, performance, TRS --- version: "Working version" language: "en" --- # Migrating to Jira Cloud from Jira Data Center If you are migrating from Jira Cloud from Jira Data Center, please create a support request. The SodiusWillert team has tools to enable the migration of OSLC Connect Links from Jira Data Center to Jira Cloud when the migration is performed using the build-in Atlassian Jira Migration (JCMA) tooling. Our migration tooling will enable * Export of OSLC Connect Data Center Configuration * Import of OSLC Configurations to the Broker * Update of OSLC links in Jira Cloud to point to the Broker * Update ELM (and soon Polarion) Links and Project Associations Users should engage the SodiusWillert team early to assess their migration target and expectations. --- version: "Working version" language: "en" --- # News You can find the latest news in our Blogs. OSLC Connect for Jira OSLC Connect for Confluence For the latest Release Notification, please join the watchlist on our Atlassian Marketplace pages. --- version: "Working version" language: "en" --- # No route to host ## Applies to * OSLC Connect for Windchill 3.5+ * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem Admin entered a Root Services URL whose host name cannot be reached. ## Cause Connection to the OSLC Remote Application failed with `NoRouteToHostException`. ## Resolution You may want to check the following step by step: * open the Root Services URL from your browser * if a document (that is not an error) is displayed or downloaded, then it means that the server is up and running * else, you will need to ensure with the person responsible for the OSLC Remote Application's server it is up \& running, as well as the OSLC Remote Application itself * if you're told the server is up and running and you still can't access the Root Services URL * you will want to confirm that you can reach the application at all. Any URL expected to work to reach that application can be tested * if you can't reach the application at all * reach out to your IT support so that they enable communication between your computer and the OSLC Remote Application's server. They may check the port is opened, the firewall is allowing communication, the routers enable transparent communication between the networks of both applications... * if you can reach the OSLC Remote Application but you still can't access the Root Services URL * you will want to confirm the OSLC services have been properly installed / enabled with the person responsible for the OSLC Remote Application, in case those services are optional or an add-on * when the server is up and running, you can reach the Root Services URL, and still the problem persists * reach out to your IT support so that they enable communication between your application's server and the OSLC Remote Application's server --- version: "Working version" language: "en" --- # OAuth Problem additional_authorization_required ## Applies to * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem This error should not be encountered under normal uses of our products as it offers no API to reproduce it manually. Advanced users with the proper knowledge of OAuth flows could use browser's tools to reproduce this. ## Cause In the middle of the OAuth dance, the user needs to confirm that the remote application can access Jira on its behalf. To achieve this, the remote application opens a popup window and loads the Jira login page. When the user grants access, the connector marks the OAuth request token as *authorized*and the popup window is closed. It is only when the popup window is closed, that the remote application knows it must continue with the OAuth dance. The next step is to ask Jira to interchange the request token for an access token, and for that, the request token must be marked as *authorized*. To reproduce this error, the remote application must continue with the dance without waiting for the user to approve the remote access. This cannot be emulated on Jira, because there's currently no API to unmark an already-marked token. Trying to get it by a race condition will be hard too because the remote application is waiting for a callback notification to resume the dance (just before closing the window). --- version: "Working version" language: "en" --- # OAuth Problem token_rejected ## Applies to * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem This error should not be encountered under normal uses of our products as it offers no API to reproduce it manually. ## Cause In the code, this error mainly exists to check for missing request tokens in the server cache or to prevent object casting issues in the code. As such, there is no reproduction procedure for this error. Atlassian document this issue as possible with applications that allows OAuth tokens to be manually revoked. In such cases, this error might appear in the log files but the user should be prompted with the login page instead of an error. **Related documentations** --- version: "Working version" language: "en" --- # OAuth Problems This section contains troubleshooting information related to OAuth problems in OSLC Connect tools. * [\[OCFD-SRV045\] Friend application has not granted you access](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv045-friend-application-has-not-granted-you.md) * [\[OCFD-SRV045\] timestamp_refused](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv045-timestamp_refused.md) * [\[OCFD-SRV045\] parameter_absent](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv045-parameter_absent.md) * [\[OCFD-SRV045\] signature_invalid](https://docs.sodiuswillert.com/oslc-connect/latest/ocfd-srv045-signature_invalid.md) * [HttpUnauthorizedException in LDX or LQE](https://docs.sodiuswillert.com/oslc-connect/latest/httpunauthorizedexception-in-ldx-or-lqe.md) * [OAuth Problem additional_authorization_required](https://docs.sodiuswillert.com/oslc-connect/latest/oauth-problem-additional_authorization_required.md) * [OAuth Problem token_rejected](https://docs.sodiuswillert.com/oslc-connect/latest/oauth-problem-token_rejected.md) --- version: "Working version" language: "en" --- # \[OCFD-SRV022\] HTTP scheme mismatch ## Applies to * OSLC Connect for Windchill 3.5+ * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem Friending failed to complete because of scheme mismatch. ## Cause Admin entered a Root Services URL whose scheme is `HTTP` and OSLC Connect is `HTTPS` (or vice versa). This is enforced by OSLC Connect tools to prevent problems in subsequent OSLC interactions. Indeed, modern browsers are adding security constraints, and restricting `HTTPS` to `HTTP` interactions is amongst those. ## Resolution As an Admin, you are required to configure and use HTTPS for OSLC enabled applications. As such, you can use an `HTTPS` Root Services URL to perform the friending. ![image-20210604-145714.png](https://docs.sodiuswillert.com/__attachments/a_e47a4c3efaaf290a74a62755dd4daf60ef5f8446f9ee556edffa7614bc93a951/image-20210604-145714.png?cb=5016625076bea865954f81366426db4a) --- version: "Working version" language: "en" --- # \[OCFD-SRV023\] Root Services document is already registered ## Applies to * OSLC Connect for Windchill 3.5+ * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Symptom Friending is refused by OSLC Connect tool. ## Cause Admin enters a Root Services URL already used by a registered friend. ## Resolution Since there is no need to have two friends for the same Root Services document, simply stick to registering it only once. ![image-20210604-150247.png](https://docs.sodiuswillert.com/__attachments/a_1ebdd05f96f5f6d1fcef69fb35d0d085f5eb4da03b2e68c03cf68961e62095a0/image-20210604-150247.png?cb=a81a204855e9cc6107a858eb9971c8ab) --- version: "Working version" language: "en" --- # \[OCFD-SRV024\] Local storage for the friend fails ## Applies to * OSLC Connect for Windchill 3.5+ * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem Information entered by the Admin is valid but the storage for this information in the OSLC Connect database fails. ## Cause An error occurred in the OSLC Connect application or database. ## Resolution Depending on the application, it could be a database issue or a file storage storage issue. You should review the logs to identify and resolve. ![image-20210607-122928.png](https://docs.sodiuswillert.com/__attachments/a_88dc997a0c08fbe0feeb8b95e726a3224a7b35fe19cfab5300f525e1e7e34371/image-20210607-122928.png?cb=c735e4954985ea75089089421ff8e6d6) --- version: "Working version" language: "en" --- # \[OCFD-SRV027\] Provisional key generation is not supported ## Applies to * OSLC Connect for Windchill 3.5+ * OSLC Connect for Jira 2.7+ * OSLC Connect for Confluence 1.1+ ## Problem Admin requested to generate a provisional key but OSLC Remote Application doesn't have support for this. ## Cause Technically, the Root Services document for the OSLC Remote Application is missing the `jfs:oauthRequestConsumerKeyUrl` property. ## Resolution You should ask the OSLC Remote Application's admin to first create a consumer key that can then be used in OSLC Connect when registering a friend. ![image-20210607-122649.png](https://docs.sodiuswillert.com/__attachments/a_573ae83a3e9de71678b79d213e757b2e676d8de05c2b216cbcb74dbe029ec5d8/image-20210607-122649.png?cb=379564be25959cc5bf829e8e7eff513a) [Next Page](https://docs.sodiuswillert.com/llms-full.txt/1)