Prerequisites

The following steps should already have been done before you install the OSLC Connector for Preevision. Please make sure that:

The OAuth client MUST fulfill the following requirements:

has to be a public client
has to be OIDC
grant type must be authorization code
one redirect URI must be https://<oslc connector url>/login/oauth2/code/custom
the other redirect URI must be the Preevision API redirect URI

The technical OAuth client MUST fulfill the following requirements:

has to be a private client (so it has a key and secret)
grant type must be authorization code
one redirect URI must be https://<oslc connector url>/login/oauth2/code/custom
the other redirect URI must be the Preevision API redirect URI

server certificates for your https://genoslc-Preevision.<your domain> are present. The certificates must fulfill the requirements stated in this section: Creating and testing the Certificates for Smartfacts | Create the certificate
the DNS entry is active for https://genoslc-preevision.<your domain>
your OSLC Connector for Preevision deployment can reach the target Preevision instance; all necessary proxies are configured to allow the communication from the OSLC Connector to the Preevision instance

Prepare the Deployment

Add library Repository for the OSLC Connector for Preevision

You will need a username and password to download the helm chart and containers from MID's repository. You will receive username and password from your MID contact or from cops@mid.de.

sudo helm repo add library https://repo.secure.mid.de/chartrepo/library --username <USERNAME> --password <PASSWORD>
sudo helm repo update

Customize Values File

Change to your user's home directory on the server and create a new text file values-genoslc-Preevision.yaml with the following content:

genoslcToolServiceVersionOverride: ""

global:
  # Domain of the cluster or of the external reverse proxy
  domain: "example.com" 
  
  # Setup OIDC information
  oidc:
    # OIDC Client ID registerd for this application
    clientId: ""
    # OIDC Client Secret registered for this application
    clientSecret: ""
  
  # SSL certificates
  cert:
    overrideTruststorePassword: "changeit"
    secretName: ""
    crtFullChain: ""
    key: ""

  identity:
    # OIDC Issuer URL, taken from the /.well-known/openid-configuration endpoint 
    OIDC_ISSUER: ""
  hosts:
    genoslc:
      # The subdomain where the OSLC Connector for Preevision will be accessible
      subdomain: "genoslc-Preevision"  
      port: ""

env:
  tool:
    type: "preevision"
    adaptedToolApiUri: ""
    adaptedToolRootUri: ""
    adaptedToolToolTimeZone: "UTC"
    getProductLine: ""
    getProductlinesRequs: ""
    getReqTable: ""
    getReqTree: ""
  manualLoginRequired: "false"
  authorizationUri: ""
  introspectionUri: ""
  configuration:
    administrators: []
    oauth10aEncryptionKey: ""  
  oidc:
    clientId: ""
    clientSecret: ""
    secretName: ""
    technicalUserClientId: ""
    technicalUserClientSecret: ""
    technicalUserClientScope: "openid"
  userNameAttribute: "preferred_username"
  clientAuthenticationScheme: "client_secret_basic" 
  userInfoAuthenticationMethod: "header" 
  clientScope: "openid"
  pkceEnabled: true
  publicUri: ""  
  pluginUri: ""
  allowedCorsOrigins: ""
  knownContextRoots: ""
  globalConfigurationProvider: ""
  linkIndexType: ""
  linkIndexUri: ""
  linkValidityProvider: ""
  trsEnabled: false
  
  containerPort: "8443"
  port: "8443"
  debugPortToolService: ""
  
  # Defines a proxy used by the OSLC Connector for Preevision. 
  proxy:
    https:
      # The URL of the https proxy server
      host: "" 
      # The port of the https proxy server
      port: ""
      # A list of IP addresses or URLs devided by the pipe sign '|'
      nonProxyHosts: "" 

  # Sets the logging level in the application
  # valid values are: INFO, ERROR, DEBUG, TRACE
  loggingLevelSpringFramework: "INFO" 


ingress:
  enabled: true
  className: ""
  annotations: {}
  tls:
    secretName: ""


  # ----------------------------------------------------------------
  # ------------------------- Library ------------------------------
  # ----------------------------------------------------------------

# Special certtool configuration
certtool:
  # certtool should only be activated on the first deployment and after a certificate update
  enabled: true
  
mongodb
  # Deployes a mongodb container inside the pod that the OSLC Connector will use
  enabled: true

Overwriting the installed version

Use genoslcToolServiceVersionOverride to change the default version set in the helm chart for the tool service. Overwrite the default value when you want to switch to another version, other than the one set as default via the helm chart

genoslcToolServiceVersionOverride: "2024.12.1"

SSL certificates

Domain and subdomain

In the global section you must specify the domain and subdomain that form the base URL where the OSLC Connector for Preevision will be accessible.

This will result in genoslc-preevision.example.com to become the URL where the OSLC Connector is established.

OIDC Issuer

The OIDC issuer must be configured in the global section in order to establish the connection between the application and the SSO. The issuer URL value has to be retrieved from the /.well-known/openid-configuration endpoint of the SSO (RFC 8414 - OAuth 2.0 Authorization Server Metadata (ietf.org))

Configuring the OIDC client

After configuring the OIDC client in your SSO provider you must set the OIDC client ID and client secret.

Setting up a connection to the Preevision instance

Adapting a Preevision instance

There are two URLs that must be set before a integration with the API and UI of Preevision can be achieved. The first one is adaptedToolRootUri and it represents the base URL of your Preevision instance. The second one is adaptedToolApiUri and represents the API URL of Preevision. This usually follows the following path formats:

https://<Preevision instance URL>
https://<Preevision instance URL>/vCollabAPI

Preevision time zone

The Preevision time zone must be set in the OSLC Connector for Preevision too. To do that use adaptedToolToolTimeZone. For more references on the Preevision tool time zone see the documentation.

List of OSLC Connector for Preevision administrators

Provide a list of up to 5 usernames which will have the administration right to change protected settings in the OSLC Connector. Inbound details and Outbound details can be managed only by administrators. At least one administrator user must be stated here.

Encrypt oauth10a configuration data

Set the encryption key used to encrypt and decrypt the oauth10a configuration data in the database.

Overwrite global OIDC configuration

This optional section can be used to overwrite the OIDC client configuration used by the OSLC Connector for Preevision when the helm chart bundles multiple applications together.

Set the env.oidc.clientId and env.oidc.clientSecret in order to overwrite the values from global.oidc.clientId and global.oidc.clientSecret respectively.

Alternatively you can provide the name of the Kubernetes secret and the values for clientId and clientSecret will be fetched from the specified secret.

OSLC Connector for Preevision requires a technical user to achieve various functionalities, making machine to machine requests to the Preevision API. For this reason a technicalUserClientId and technicalUserClientSecret must be set.

User name attribute

Used to set the JWT claim to be used for user identification. Examples are preferred_username, sub, oid.

Client authentication scheme

Sets the client authentication method to be used in the authentication process. Valid values are: client_secret_basic, client_secret_post, none. Default value is "client_secret_basic"

User info authentication method

Sets the user info authentication method. Valid values are: header, form, query

Client scopes

Sets the client scopes used in the authentication process. Default value "openid". The value is a comma separated list of scopes (e.g. "read, write").

PKCE

Sets the application to use PKCE when authenticating the user PKCE for OAuth 2.0 . Default value is true. Set pkceEnabled to false if the OIDC provider does not support PKCE.

Authorization URI

By default, the authorization URI will be retrieved from the issuer URI. However, if you need to configure custom query parameters for the authorization request you can set it up; e.g. for acr_values

Introspection URI

The introspection URI will be used to validate and retrieve token data necessary for user identification.

Public URI and Plugin URI

The env.publicUri variable sets the URL where the OSLC Connector for Preevision is accessible. This is mandatory and has to be set.

The env.pluginUri sets the URL where the OSLC Connector for Preevision is accessible and must be in the form of <env.publicUri>/spa. This variable is also mandatory and must be set.

Allowed CORS URLs

This is a comma separated list of applications that are allowed to make requests to the OSLC Connector API like third party applications that read data from the OSLC Connector for Preevision.

Known context roots

This is a comma separated list URLs of other OSLC Connectors (Smartfacts, Jama, PREEvision, Preevision, DOORS Classic) that are connect to this instance via an association.

Global Configuration Provider

Sets the Global Configuration provider. An example is https://<ibm-elm>/gc. Setting the value is optional but is mandatory if IBM ELM link validity is required.

The value must be the rootservices URL without the trailing /rootservices.

Link Index Type

Sets the type of link index used. A link index is generally used when links are retrieved by the OSLC Connector for Preevision from an external link index (e.g. LDX or Smartfacts Link Index).

e.g. Requirements are handled in Preevision and test cases in Jazz ETM - links must be read from LDX

Available options are: "ibm-elm", "smartfacts", "none"

Links Index URI

Provides the querying endpoint for the link index.

Must be configured only if env.linkIndexType has been set to ibm-elm or smartfacts.

Link Validity Provider

Sets the Link Validity Provider. Examples:

https://<ibm-elm>/jts/elm
https://<smartfacts>/platform/elm

Enabling TRS

Enables TRS feed generation. Requires a technical user to be set via the env.tool.adaptedToolTechnicalUserAuthorizationHeader if it's enabled.

TRS feed exposes base artifacts and changes that occurred in synchronized Preevision projects.

Metrics

Certain metrics are required by the OSLC Connector for Preevision in order to retrieve components and artifacts. The Preevision administrator is responsible of generating the metrics and gathering the values to be filled in the values.yaml.

Install the OSLC Connector for Preevision

Execute the Installation

Enter the following command to execute the Installation:

Next Steps

To configure communication between Preevision, OSLC Connector for Preevision and Smartfacts, please follow the steps at Tutorial Codebeamer <> Cameo Systems Modeler.

Smartfacts Public Documentation

Deploying the OSLC Connector for Preevision