6. pure::variants Web Integration
Prev   

6. pure::variants Web Integration

6.1. IBM Rational DOORS NG Web Integration

The pure::variants Integration for DOORS NG is distributed in a WAR archive (com.ps.consul.web.ui.doorsng-x.x.x.war) and can be found in the pure::variants Windows Installer package on the pure::variants update site.

Note

For brevity we have renamed the war-archive to pvwidget.war. At least for Apache Tomcat, the war-archive name implies the context-path, so the pure::variants Integration's Catalog will be reachable at https://[pv-server-FQDN]:[port]/pvwidget/catalog.xml.

Remember FQDN is the fully qualified domain name. The port number might be optional, if configured with standard SSL port (443)

The deployment of pure::variants Integration for DOORS NG has the following requirements:

Apache Tomcat 8.5.x is recommended for deployment.

The pure::variants Integration for DOORS NG must be deployed on your application server. This has to be done once by the system administrator. It entails copying of pvwidget.war into the webapps directory, which is located in the Apache Tomcat installation directory.

Note

In a Tomcat deployment, name of the war file becomes the context path of the web application. In order to configure a nested context path for a web application, the name of the war should contain the individual context path parts separated by '#'. For example, to make the pure::variants Integration's Catalog accessible by a url like https://localhost:8443/pv/widget/dng/catalog.xml, the name of the war file needs to be named as pv#widget#dng.war. And the war file should be placed into the webapps directory. For further details please see the Official Tomcat documentation.

As pure::variants Integration does client requests to DOORS NG application server, the Integration's client must be configured with the trusted SSL-certificates. One way to do this is to create a keystore, add the DOORS NG SSL-certificate to it and configure Tomcat's Java-Runtime with this keystore as a trust store.

In case of Windows, please create and open [TOMCAT_INSTALL_DIR]/bin/setenv.bat file to add the following lines:

set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustAnchors=[TRUST_STORE_PATH]"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore=[TRUST_STORE_PATH]"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStorePassword=[TRUST_STORE_PASSWORD]"

An example configuration could look like this:

set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustAnchors=c:\keystore.jks"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore=c:\keystore.jks"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStorePassword=password"

In case of Linux, please create and open [TOMCAT_INSTALL_DIR]/bin/setenv.sh file to add the following lines:

export JAVA_OPTS=$JAVA_OPTS" -Djavax.net.ssl.trustAnchors=[TRUST_STORE_PATH]"
export JAVA_OPTS=$JAVA_OPTS" -Djavax.net.ssl.trustStore=[TRUST_STORE_PATH]"
export JAVA_OPTS=$JAVA_OPTS" -Djavax.net.ssl.trustStorePassword=[TRUST_STORE_PASSWORD]"

An example configuration could look like this:

export JAVA_OPTS=$JAVA_OPTS" -Djavax.net.ssl.trustAnchors=c:\keystore.jks"
export JAVA_OPTS=$JAVA_OPTS" -Djavax.net.ssl.trustStore=c:\keystore.jks"
export JAVA_OPTS=$JAVA_OPTS" -Djavax.net.ssl.trustStorePassword=password"

Stop the Apache tomcat. Go to the Apache Tomcat installation directory, go in to work directory then go in to Catalina directory and delete the localhost directory. Go back to Apache Tomcat installation directory, go in to webapps directory and delete the previously installed pvwidget.war and pvwidget directory. Now copy the new pvwidget.war in the webapps directory and start the Apache Tomcat again. No configuration change in Apache Tomcat is required in case of an update.

WebSphere Liberty Kernel v19.0.0.6+ is recommended for deployment.

Please follow the following steps for Websphere Liberty setup:

  1. Install the WebSphere Liberty according to the official documentation.

  2. Create a server by running the following command:

    bin\server create [SERVER_NAME]

  3. Please add the following lines into the server.config.dir/server.xml file:

    <featureManager>
  <feature>jsp-2.3</feature>
  <feature>ssl-1.0</feature> 
</featureManager>

    Please run the following command:

    bin\installUtility install [SERVER_NAME]

Please ensure that the server is configured with SSL. Please refer to the Securing communications with Liberty section of the official documentation.

Copy the war archive file pvwidget.war to server.config.dir/apps. Add following line into the server.config.dir/server.xml file:

<webApplication contextRoot="pvwidget" location="${server.config.dir}/apps/pvwidget.war"/>

Note

Nested context path can be configured by specifying the whole path in contextRoot attribute of the webApplication. For example, to make the pure::variants Integration's Catalog accessible by a url like https://localhost:8443/pv/widget/dng/catalog.xml, the contextRoot attribute should be configured as contextRoot="pv/widget/dng".

The final server.config.dir/server.xml file should look similar to this:

<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">
  <!-- Enable features -->
  <featureManager>
    <feature>jsp-2.3</feature>
    <feature>ssl-1.0</feature>
  </featureManager>
  
  <httpEndpoint host="*" httpPort="-1" httpsPort="9443" id="defaultHttpEndpoint"/> 
  <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="SSL"/>
  <keyStore id="defaultKeyStore" location="keystore.jks" password="{xor}LykrOiwr" type="JCEKS"/>

  <webApplication contextRoot="pvwidget" location="${server.config.dir}/apps/pvwidget.war"/>
</server>

As pure::variants Integration does client requests to DOORS NG application server, the Integration's client must be configured with the trusted SSL-certificates. One way to do this is to create a keystore, add the DOORS NG SSL-certificate to it and configure Liberty's Java-Runtime with this keystore as a trust store. Please create and open server.config.dir/jvm.options (see Directory locations and properties) to add the following lines:

-Djavax.net.ssl.trustAnchors=[TRUST_STORE_PATH]
-Djavax.net.ssl.trustStore=[TRUST_STORE_PATH]
-Djavax.net.ssl.trustStorePassword=[TRUST_STORE_PASSWORD]

An example configuration could look like this:

-Djavax.net.ssl.trustAnchors=c:\keystore.jks
-Djavax.net.ssl.trustStore=c:\keystore.jks
-Djavax.net.ssl.trustStorePassword=password

Stop your Web Application Server (like Tomcat or WebSphere Liberty. Replace the pvwidget.war in the server.config.dir/apps directory. Start the web server again.

If you have used the pre-defined settings, as described in the section Section 6.1.8, “Pre-defined settings for Web Integration in DOORS NG”, please re-add the settings.json file accordingly, as done before.

Once finished, please start your Web Application Server again.

In order to uninstall pure::variants Integration for DOORS NG, stop the Apache Tomcat. Please go to Apache Tomcat installation directory and then go to webapps directory. Delete the pvwidget.war file and the pvwidget directory from the webapps folder.

Go back to Apache Tomcat installation directory, go in to work directory and then go in to Catalina directory and delete the localhost directory from it. Start the Apache Tomcat.

In order to uninstall the pure::variants Integration for DOORS NG, please stop the WebSphere Liberty server. Go to server.config.dir/apps folder and remove thepvwidget.war. Edit the server.config.dir/server.xml and remove the following line from the file. 

<webApplication contextRoot="pvwidget" location="${server.config.dir}/apps/pvwidget.war"/>

Save the file and start the WebSphere Liberty server again.

In order to visualize the variability, folloing settings need to be configured on the Jazz side.

Browse to JTS home page. Click Manager Server and then click Advanced Properties in the left menu.

Scroll down to OpenSocial gadget enable SSO and set its value to true as shown in figure Figure 57, “OpenSocial gadget enable SSO Setting”.

Figure 57. OpenSocial gadget enable SSO Setting

OpenSocial gadget enable SSO Setting

For the versions ELM 7.0.2 iFix004, ELM 7.0.1 iFix009, CLM 6.0.6.1 iFix018, CLM 6.0.6 iFix022 and onwards, an extra configuration is required. In External resources allowlist, please enter the URL of the widget. For example if pure::variants Integration for DOORS NG is accessible at https://jazz.server.net:8443/pvwidget/catalog.xml then enter https://jazz.server.net:8443/pvwidget/ in the allowlist as shown in the figure Figure 58, “External resources allowlist”.

Figure 58. External resources allowlist

External resources allowlist

Further, scroll down to Jazz Authentication Services, in Jazz Authentication Proxy SSO Cookies field and replace its value with LtpaToken, LtpaToken2, JSESSIONIDSSO, JSA_SESSION_IDENTITY. In the next field in Jazz Authentication Proxy SSO Whitelist, write the URL of the server hosting the widget. Assuming that pure::variants Integration DOORS NG war was renamed as pvwidget.war, the URL must end with /pvwidget/vel as shown in the figure Figure 59, “Jazz Authentication Proxy SSO Settings”.

Figure 59. Jazz Authentication Proxy SSO Settings

Jazz Authentication Proxy SSO Settings

As shown in Figure 60, “Adding A URL In RM Whitelist”, go to Jazz RM application administration page. Click the Whitelist (Outbound) on the left menu. In the Enter Base URL field of the Add New Whitelist URL section, enter the Base URL of the server where the pure::variants Integration for DOORS NG is installed. Click Add button and the newly added URL should be added to the Outbound URL list on the same page.

Figure 60. Adding A URL In RM Whitelist

Adding A URL In RM Whitelist

Note

On clicking the Add button, Jazz tries to access the URL being added. And if the URL is accessible only then the URL is added to the list of Outbound URL.

Browse to Jazz RM Advanced Settings page. RM Advanced Settings page can be accessed by pointing the web browser to following URL:

 https://<server>:<port>/rm/admin#action=com.ibm.team.repository.admin.configureAdvanced

Scroll to User Extension Catalog URL as shown in figure Figure 61, “RM User Catalog Configuration”.

Figure 61. RM User Catalog Configuration

RM User Catalog Configuration

Considering that the context path of the pure::variants Integration is pvwidget, enter the Catalog URL as https://<server>:<port>/pvwidget/catalog.xml and Save the settings.

Jazz RM allows configuration of only one Catalog URL. If you already have a Catalog URL configured in RM Advanced Properties. Then the pure::variants Integration for DOORS NG can be added to the existing catalog document. Lets consider that pure::variants Integration for DOORS NG is deployed on a web server and accessbile via a URL like this: 

https://server.local.com:8443/pvwidget/catalog.xml

Open the catalog xml document that is already configured in the RM Advanced Properties. Add the following ju:catalog-entry in the list of existing ju:catalog-entry nodes.

<ju:catalog-entry>
	<dc:title>pure::variants Integration</dc:title>
	<dc:description>Enables adding variability information to requirements in a DOORS NG module. Enables editing of Restrictions and Calculations. Also provides the functionality of creating a Variability Preview.</dc:description>
	<ju:gadget rdf:resource="https://server.local.com:8443/pvwidget/pvscl.xml"/>
	<ju:icon rdf:resource="https://server.local.com:8443/pvwidget/pv.png"/>
	<ju:preview rdf:resource="https://server.local.com:8443/pvwidget/preview.png"/>
	<ju:thumbnail rdf:resource="https://server.local.com:8443/pvwidget/thumbnail.png"/>
	<ju:category>pure::variants</ju:category> 
	<ju:category>Requirements</ju:category> 
</ju:catalog-entry>

Note

Please note that the starting URL in the ju:gadeget, ju:icon, ju:preview and ju:thumbnail depends on the deployement of the pure::variants Integration. Try to access the ju:gadget URL in browser and see if the pvscl xml document is shown or not. If the xml document is shown in the browser then the pure::variants widget should be available in the 'Add Widget' dialog.

In order to interact with the Integration, it needs to be added inside Jazz' Mini Dashboard. Hence, open the Mini Dashboard on the left side panel inside DOORS NG. At the top left of Mini Dashboard, click the Add Widget button. A dialog opens as shown in the figure Figure 62, “Adding Integration inside Mini Dashboard”.

Figure 62. Adding Integration inside Mini Dashboard

Adding Integration inside Mini Dashboard

On the left side of the dialog, in the widget category, click pure::variants. Then under the pure::variants Integration click the Add Widget.

For further instructions see section Adding an OpenSocial gadget in the documentation of IBM's Rational Collaborative Lifecycle Management

Note

If pure::variants Integration for DOORS NG is going to be used in Web Hub mode with Jazz V7.0 then it is required that the pure::variants Web Components' relative domain-name must be same as DOORS NG's relative domain-name (e.g. *.local.net). For example, if DOORS NG is accessible via https://server.local.net:9443/rm then pure::variants Web Components must be accessible via URL like https://otherserver.local.net:8443/pv.

If a common domain-name is not possible, the WebComponents should be configured regarding SameSite attributation for Cookies. For this, please see the optional step in our Tomcat resp. WebSphere configuration guide.

The following list contains all necessary steps to be have taken to make successful deployment of the DOORS NG integration along with the DOORS NG application:

The Web Integration for DOORS NG allows you to pre-define specific settings to ease up or limitate the setup for end-user.

Please see chaper Section 6.2, “Pre-defined settings for Web Integration” for detailed explanations, which settings are available and how they are configured.

To use these pre-defined settings for DOORS NG Integration, you need to write the configuration (in JSON format) into a file called settings.json and put this into the deployment directory.

If your Web Application Server (like Tomcat or WebSphere Libterty) extracts the war-archive automatically, please add the settings.json file into the war-archive (called "com.ps.consul.web.ui.doorsng.*.war"

If your Web Application Server (like Tomcat or WebSphere Libterty) does not extract the war-archive automatically and you extract it manually, please add the settings.json into the deployment directory of the Integration.

Finally, the deployment directory should have located the settings.json next to the pvscl.xml, as follows:

|-META-INF
|-WEB-INF
|-pvscl.xml
|-settings.json
|-... (other files)

6.2. Pre-defined settings for Web Integration

As administrator, you can pre-define the settings for the end-user, e.g. to connect to the WebHub immediately. Thus, the user must not be aware of the WebHub URL and can use the Widget out-of-the-box.

Therefore, a JSON structure must be created as described in the following:

{
     "PV_HUB": "webhub",
     "PV_HUB_URL": "https://webhub.server/pv",
     "PV_HUB_EDITABLE": true,
     "PV_HUB_URL_EDITABLE": true,
}

The PV_HUB property defines the hub to be used, which can be either the WebHub (webhub) or DesktopHub (desktophub).

The PV_HUB_URL property defines the URL for the WebHub.

The PV_HUB_EDITABLE property defines if the hub should be still editible by the user. If not defined, the hub is still editable by user in widget.

The PV_HUB_URL_EDITABLE property defines if the webhub URL should be still editible by the user. If not defined, the webhub URL is still editable by user in widget.

Note

Please see the respective sections of Web Integrations, like Polarion, Codebeamer or DOORS NG, how the JSON structure must be deployed.

Prev   
5. pure::variants Tool Integrations Home