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 ->
Or the OSLC Connect for Jira Status Page (https://myjiraserver/plugins/servlet/oslc/status)
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.
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
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.
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 https://myjiraserver/plugins/servlet/oslc/trs.
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.
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.
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.
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.
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.
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.
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)
Two data sources in LQE (Process and CM Resources)
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.
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"