The following fields have to be created for the solution item, e.g. MKS Solution. In the PTC Integrity Administration open Workflows and Documents -> Fields. Add the fields by choosing Create Field... from the context menu.

Figure 38. Added fields

Figure 39. Solution Types

Figure 40. Fields added to type Requirement Document

pure::variants uses following settings in order to connect to PTC Integrity. This includes settings for the pure::variants Connector for PTC Integrity, which allows importing and exporting documents, as well as the settings for the In-tool Integration, which allows adding and changing restriction rules in PTC Integrity.

Some of these settings can be directly changed before importing and exporting requirement documents. Others can only be changed in the connector configuration file and in the solution type. The following table shows the property names used to change these settings in the configuration file and the solution type.

To change these settings in the connector configuration file, create the file pvIntegrity.properties in directory %APPDATA%\pure-variants-6. For each setting to change, add a line with the config file property of the setting assigned to the new value. To change for instance the default field used for storing restriction rules to MyRestriction and the default field used for storing the enumerated variants to MyEnumeratedVariants, you would add the following two lines to the configuration file (the comments are optional):

# Field used to store restriction rules
attrname.restrictions=MyRestriction
# Field used to store enumerated variant names
attrname.variants=MyEnumeratedVariants

To change these settings on the solution item, open the Administration of PTC Integrity. Switch to Workflows and Documents -> Types and select the solution type (e.g. MKS Solution).

Figure 41. Type MKS Solution

Figure 42. Added Properties

Several fields of the original document are copied while creating a document variant. This includes the fields mentioned in section Section 5.4.1, “Add additional Fields for pure::variants” but also some fields that are copied by default. The list of fields that are to be copied by default can be configured by the Integrity administrator.

To additionally copy for instance decompose relationships, the administrator has to open the Administration of PTC Integrity. Then switch to Workflows and Documents -> Types and edit type Requirement. Open the Copy Fields list and add the fields Decomposes To and Decomposed From. This way fields could be added for the types Requirements Document, Requirement, and Shared Requirement.

Figure 43. Decompose Fields added

The connector and the integration for PTC Integrity require access to the Integrity client in order to work. Start the PTC Integrity client and open menu File -> Preferences. For the entries Integrity Client, Workflow and Documents, Configuration Management, and Authorization Administration click the Connection section and enable Prompt for Host Name and Port, prompt for User Name, and prompt for Password.

Figure 44. pure::variants Credentials

In RTC two integrations need to be installed: The IBM Rational Rhapsody integration for Rational Team Concert and the pure::variants Integration for RTC transformation. The IBM Rational Rhapsody integration for RTC is needed for RTC to work with RMM projects. Please consult the RTC documentation for installation instructions.

The pure::variants Integration for RTC transformation is needed during transformation of RMM projects. Without it, the transformation will fail. To install the pure::variants Integration for RTC transformation, please open RTC and use Help > Install New Software to install all contents of archived update site com.ps.consul.eclipse.rtc.integration.feature_[version].zip. You can find the archived update site zip in your Rhapsody integration installation folder (default is C:\Program Files\pure-systems\pv_Enterprise_6.0\com.ps.consul.eclipse.ui.rhapsody.integration).

For the transformation of RMM projects to work, you still need to set the RTC executable location. You can do this in the pure::variants preferences at Window > Preferences > Variant Management > Connector Preferences > Connector for IBM Rational Rhapsody. Alternatively, you can define an environment or Java system variable that is named PV_RTC_EXEC_PATH and whose value points to the RTC executable location.

When using Rhapsody 9.0 or above, it is possible to run a transformation of RMM projects in offline mode. This means that the transformatin is carried out without starting RTC/EWM client. At the above mentioned preference page, you can select the checkbox to enable this feature. Alternatively, you can set an environment or Java system variable that is named PV_RHAPSODY_RMM_OFFLINE_MODE to true to set the offline mode.

Additionally, you can set a custom location of RTC/EWM's eclipse.ini and lscm.bat files. You can set an environment or Java system variable that is named PV_RTC_INI_PATH to set the location of the eclipse.ini file and PV_RTC_LSCM_BAT to set the location of the lscm.bat file. If this is not set, the trasformation will look for it in the default location.

Follow the steps as described in ‘3.1. Install pure::variants Desktop Client’, in case installing pure::variants into an eclipse client, see chapter ‘3.1.2. Install into an existing Eclipse’.

Following components that are delivered as part of the pure::variants Enterprise installation package need to be installed on the Codebeamer server:

The server component is a Spring based custom component running in the application context as defined for Codebeamer (for details see https://codebeamer.com/cb/wiki/18830).

Before deploying, unzip the jar files 'com.ps.consul.codebeamer.vel.jar' and 'pvcore.jar' from the zip archive of the server component. Also make sure the server certificate that is used by the Codebeamer server is trusted on the pure::variants Desktop Client side.

Similarly, the folder 'pv_integration' contained in the zip for the to the pure::variants Widget needs to be unzipped.

Follow the steps to install:

When running Codebeamer server in a docker container (https://codebeamer.com/cb/wiki/5562876), following additional information needs to be defined in the docker compose configuration file:

volumes:
      -./com.ps.consul.codebeamer.vel.jar:<codebeamer>/tomcat/webapps/ROOT/WEB-INF/lib/com.ps.consul.codebeamer.vel.jar
      -./pvcore.jar:<codebeamer>/tomcat/webapps/ROOT/WEB-INF/lib/pvcore.jar
e.g. 
- ./libs/com.ps.consul.codebeamer.vel.jar:/home/appuser/codebeamer/tomcat/webapps/ROOT/WEB-INF/lib/com.ps.consul.codebeamer.vel.jar
- ./libs/pvcore.jar:/home/appuser/codebeamer/tomcat/webapps/ROOT/WEB-INF/lib/pvcore.jar

To deploy the 'pure::variant Widget to Codebeamer' following additional information needs to be added to the docker compose configuration file:

volumes:
      - ./pv_integration/widget:<codebeamer>/tomcat/webapps/pv-widget/

e.g. 
- ./pv_integration/widget:/home/appuser/codebeamer/tomcat/webapps/pv-widget/

Then follow the steps to install:

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

Please see chapter Section 7.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 Codebeamer Web Integration, you need to write the configuration (in JSON format) into a file called settings.json and put this into the deployment directory.

This settings.json must be placed into the existing deployment directory of the Integration.

E.g. <codebeamer>/tomcat/webapps/pv-widget/

|-index.html
|-extension.json
|-settings.json
|-... (other files) 

{
  "SSO_SERVER_URL: "https://codebeamer.server:9443/"
}          

The communication of pure::variants Desktop Client and Widget to Codebeamer application uses the Codebeamer REST API. In order to use the REST API end points, the user needs to have Rest / Remote API - Access permissions.

To do this, make sure the user group that the users are assigned to in Codebeamer have this permission set via System Admin->User Groups menu.

Use following REST call to query the version information of the server component, this way it can be checked if the server component is running correctly:

https://<path_to_codebeamer>/rest/v3/ps/vel/version

Note: Use the credentials (basic authentication) of a Codebeamer user with 'api_permission'.

OpenID Connect (OIDC) is an authentication protocol that is an extension of OAuth 2.0.

According to this, a dedicated system (Authorization server/ Identity provider) takes care of authenticating a user and issuing access and id token if authentication was successful. This token can be used by clients to obtain data from the Resource Server, in this case the Codebeamer server. The REST API of Codebeamer requires such access token to enable this way of authentication.

To obtain the access token an Authentication Proxy needs to be deployed between the client and the server. All REST API calls are redirected through it, while the authentication process including the refreshing of the tokens is also managed by this proxy in the background.

Figure 45. Authorization process using a proxy

This file configures the auth-proxy service that is required by the pure::varaints client. The docker container image named “oidc-auth-proxy” will be created and started, on which NGINX service will be available, which in-turn will be used by pure::variants Desktop Client to make the REST calls.

Following parameters are to be set:

Any dependent container(s) that will be used by oidc-auth-proxy or any additional container that needs to be built together can be deployed on the same docker machine by adding in the new container configuration under services.

Following code listing shows an example:

version: '3.1'
services:
  oidc-auth-proxy:
    build:
      context: .
      dockerfile: oidc-auth-proxy.dockerfile
    ##Specify the port to which nginx is listening to. (host port:docker port)
    ports:
      - 9943:9943
    volumes:
      - ./oidc-auth-proxy-nginx.conf:/usr/local/openresty/nginx/conf/nginx.conf:ro
      - ./server.crt:/usr/local/openresty/nginx/server.cert:ro
      - ./server.key:/usr/local/openresty/nginx/server.key:ro
      - ./cacerts.crt:/usr/local/openresty/nginx/cacerts.crt:ro
    restart: always

This file contains the set of commands that has to be executed to build a docker image. lua-resty-openidc library for NGINX is used to authenticate user against Open ID Connect provider. Hence this file contains the command to load the base image of openresty from docker hub and then Install the required packages on the current docker image, followed by command to start the NGINX.

Following code listing shows an example:

FROM openresty/openresty:alpine-fat
RUN apk add --update openssl-dev git && luarocks install lua-resty-openidc
CMD ["/usr/local/openresty/bin/openresty", "-g", "daemon off;"]

The directives that need to be adapted are as follows:

Following code listing shows an example:

events {
  worker_connections 128;
}

http {
  resolver 127.0.0.11 ipv6=off;
  lua_package_path '~/lua/?.lua;;';
  lua_ssl_trusted_certificate /usr/local/openresty/nginx/cacerts.crt;
  lua_ssl_verify_depth 5;
  lua_shared_dict discovery 5m;
  lua_shared_dict jwks 5m;

  server {
    listen 9943 ssl; ##mention the port to which nginx should listen to
    server_name codebeamer.example.com; ##domain name or ip address of the host on which docker is running 
    ssl_certificate /usr/local/openresty/nginx/server.cert;
    ssl_certificate_key /usr/local/openresty/nginx/server.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    client_max_body_size 16m;

    location / {
      access_by_lua_block {
        local opts = {
   ##redirect_uri should match the uri pre-registered in Authorization server during client registration.
          redirect_uri_path = "/login/oauth/authenticate.spr",
  ##OpenID Connect defines a discovery mechanism where OpenID Server publishes its metadata at a well known url of the format: https://server.com/.well-known/openid-configuration
          discovery = "https://jas.example.com:9643/oidc/endpoint/jazzop/.well-known/openid-configuration",
  ##Client_id and client_secret obtained from the authorization server after the client registration.
          client_id = "<set here the client ID>",
          client_secret = "<set here the client secret>",
          scope = "openid profile email",
          access_token_expires_leeway = 30,
          accept_none_alg = false,
          accept_unsupported_alg = false,
          renew_access_token_on_expiry = true,
          access_token_expires_in=3600,
          session_contents = {access_token=true, id_token=true}
        }
        if ngx.req.get_headers()["Authorization"] == nil or (not string.match(ngx.req.get_headers()["Authorization"], "Bearer")) then
          local res, err = require("resty.openidc").authenticate(opts)
          if err then
            ngx.status = 500
            ngx.say(err)
            ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
          end
          ngx.req.set_header("Authorization", "Bearer " .. res.access_token)
          ngx.req.set_header("X-User", res.id_token.email)
        end
      }
   ##proxy_pass value can be a docker container on which Codebeamer application is running. For ex., http://container-name:8090; 
   ##or it can be a Codebeamer application server url to which a request should be forwarded. For ex., http or https://server-name:port(optional);
      proxy_pass http://codebeamer-app:8090;
    }
  }
}

Following are the steps to create a docker container image named “oidc-auth-proxy”. NGINX will available on this docker container on the specified port.

Follow the steps as described in ‘3.1. Install pure::variants Desktop Client’, in case installing pure::variants into an eclipse client, see chapter ‘3.1.2. Install into an existing Eclipse’.

The pure::variants enterprise ("pure::variants Windows Installer Package") contains the package com.ps.consul.polarion.api-<version>.zip which needs to be deployed to the Polarion server. Therefore please follow the following steps:

The previous steps are only for installing the integration. To configure the the pure::variants plugin please follow the steps in Section 5.7.3, “Configuration of pure::variants server component for Polarion”

There are several steps necessary to prepare the Polarion server for pure::variants.

              pvWidgetConnectionSettings = {
   // PV_HUB: Defines either 'webhub' or 'desktophub' as tool to connect with
   "PV_HUB": undefined,
   // PV_HUB_EDITABLE: true or false. Defines if the user is able to change the connection
   "PV_HUB_EDITABLE": true,
   // PV_HUB_URL: provide the url if webhub is defined at PV_HUB
   "PV_HUB_URL": undefined,
   // PV_HUB_URL_EDITABLE: true or false. Defines if the webhub url is modifieable
   "PV_HUB_URL_EDITABLE": true
  };