Server Guide

This guide provides details about the Open Services for Lifecycle Collaboration (OSLC) Server for codebeamer. It assumes that you are familiar with OSLC standards and specification when using the codebeamer Server.

This guide also assumes that an administrator performs the installation and configuration of the codebeamer Server. It is also assumed that this administrator has the necessary access to make changes to codebeamer server.

codebeamer Server Catalog

The codebeamer Server provides a root catalog to enable OSLC client applications to find the Service Providers and the nested Service Provider Catalogs. When a client OSLC application connects to the codebeamer Server, it can first fetch the catalog, which provides a list of Service Provider and nested Service Provider Catalog resources. The OSLC client application can use the URI of the Service Provider Catalog offered by the codebeamer Server and navigate to the Service Provider Catalog or Service Provider resources.

Installation and Configuration

No specific installation or configuration steps need to be performed to install OSLC services. The Service Provider Catalog is available when codebeamer is installed. For installation of codebeamer, refer to the codebeamer Installation Guide.

Also ensure that SSL is set up for the codebeamer server. For more information, refer to How to Set Up SSL for codebeamer.

OSLC services are available when the codebeamer server is running.

API Throttling

API throttling must be configured before using OSLC services.

To apply API throttling, do the following:

1. Visit the /sysadmin/configConfiguration.spr page.
2. Add the following cluster configuration to the application config:
   

   "apiThrottling" : {
           "urlPatterns" : "/api/oslc/**",
           "bandwidthConfigs" : {
               "capacity" : 100,
               "timeUnit" : "SECOND"
           }
       },

Content Security Policy

By default, codebeamer allows requests originating from the same domain (and origin), in a web browser. Even if the domain is the same, the origin could be different based on subdomain or port. For example, https://app1.myexample.com and https://app2.myexample.com belong to the same domain but have different origins.

To use previews, the request must be from the same domain even if the origins are different based on the subdomain. Such origins must be in the Allowed List.

To enable the security policy, do the following:

1. Visit the /sysadmin/configConfiguration.spr page.
2. Either add the following configuration to the application config:
   

   "contentSecurityPolicy" : {
         "text" : "frame-ancestors <EXTERNAL_DPT_SERVER_BASE_URL1> <EXTERNAL_DPT_SERVER_BASE_URL2>"
    },
   

3. Or, set the following environment variable:
   

   CB_CORS_ALLOWED_ORIGINS=<EXTERNAL_DPT_SERVER_BASE_URL1>,<EXTERNAL_DPT_SERVER_BASE_URL2>

The first list of servers must be separated by a space. The second list of servers is a comma-separated list.

Mapping the Requirements Management Domain

The codebeamer server only supports reporting on the Requirement resource in the Requirements Management domain resources.

The OSLC property mapping is as follows:

If you do not want to use the default mapping, you can map different Codebeamer fields to OSLC terms. The mapping that you specify will be applicable to the specified projects, based on project IDs. If a mapping is not specified for a project, the default field mapping is used.

In addition to the Codebeamer fields, you can also map a custom namespace to OSLC fields. To enable field mapping, you need to first identify the Codebeamer Tracker to get the Codebeamer field Property ID values that you want to map to Codebeamer fields.

To get the Codebeamer Field Property IDs, do the following:

1. Select the Projects tab.
2. Click a Project in the right pane.
3. Click the Trackers tab.
4. Right-click a Tracker in the tracker tree and select Configure.
5. On the Configuration screen, select the Fields tab.
6. Select Show property name check box to view the Property IDs as stored in the Codebeamer database for the given tracker.
7. Note down the Property IDs of the fields that you want to map to OSLC terms.
   The Property IDs of Shared Fields are listed at the end of the table. For information on adding Shared fields, refer to: You must login to see this link. Register now, if you have no user account yet..

Configuring the mapping of Codebeamer fields to OSLC terms

To configure the mapping of Codebeamer fields to OSLC terms, do the following:

1. Visit the /sysadmin/configConfiguration.spr page.
2. Add the OSLC mapping configuration.
3. Click Save.

Mapping Configuration Example

The mapping configuration must be added in:

oslc: {
}

A sample OSLC mapping configuration appears as follows:

"oslcFieldMappingConfigs":
{
  "oslcFieldDefinitions": [
    {
      "projectIds": [3],
      "fieldMappings": [
        {
          "cbTerm": "id",
          "oslcTerm": "dcterms:identifier"
        },
        {
          "cbTerm": "SecondShared",
          "oslcTerm": "dcterms:title"
        },
        {
          "cbTerm": "name",
          "oslcTerm": "dcterms:description"
        },
        {
          "cbTerm": "name",
          "oslcTerm": "cb:testProp"
        },
        {
          "cbTerm": "modifiedAt",
          "oslcTerm": "dcterms:modified"
        },
        {
          "cbTerm": "modifiedAt",
          "oslcTerm": "cb:testDateAttr"
        }
      ]
    },
    {
      "projectIds": [5, 78],
      "fieldMappings": [
        {
          "cbTerm": "id",
          "oslcTerm": "dcterms:identifier"
        },
        {
          "cbTerm": "SecondShared",
          "oslcTerm": "dcterms:title"
        },
        {
          "cbTerm": "name",
          "oslcTerm": "dcterms:description"
        },
        {
          "cbTerm": "name",
          "oslcTerm": "cb:testProp"
        },
        {
          "cbTerm": "modifiedAt",
          "oslcTerm": "dcterms:modified"
        },
        {
          "cbTerm": "modifiedAt",
          "oslcTerm": "cb:testDateAttr2"
        }
      ]
    },
  ],
  "namespaceAttributes": [
    {
      "name": "testProp",
      "type": "STRING"
    },
    {
      "name": "testDateAttr",
      "type": "DATETIME"
    },
    {
      "name": "testDateAttr2",
      "type": "DATETIME"
    }

  ]
}

The main field definitions appear under oslcFieldDefinitions while the custom namespace definitions appears under namespaceAttributes.

In projectIds specify one or more Codebeamer project IDs. You can obtain the project IDs from System Admin ► Projects.

In fieldMappings, specify Codebeamer Property ID-OSLC term pairs.

In this example, SecondShared is the Property ID of a Codebeamer Shared Field.

In oslcTerm, specify the OSLC terms to be mapped to Codebeamer fields.

Mapping custom namespaces

You can specify Codebeamer Shared Fields that are used globally across the product as custom namespaces. To map a custom namespace, specify the Shared Field information under namespaceAttributes.

Specify the Shared Field ID under name and the type under type. The valid values for type are STRING, INTEGER, and DATETIME.

Then map the Shared Field to a Codebeamer field under oslcFieldDefinitions, prefixing the Shared Field ID with cb.

In this example, testProp, testDateAttr, and testDateAttr2 are Shared Field IDs.

Even if you add a field mapping configuration, the terms eligible for querying remain the same.

Supported Security Schemes

The codebeamer Server supports the Basic Auth security scheme.

If the codebeamer server is configured with a security policy that requires user credentials for authentication, the OSLC client application must provide the username and password in the Basic Auth header when sending requests to the codebeamer Server.

Using the codebeamer Server

codebeamer tracker items of type Requirement are mapped to Requirement Management domain Requirement resources.

The codebeamer Server enables OSLC client applications such as Windchill to create a trace using codebeamer Requirement resources. The server also provides compact resources for accessing small previews of codebeamer Requirements that can be previewed from Windchill. For more information on resource previews, see Working with Resource Previews.

The codebeamer Server supports application/rdf+xml as the content type for all request responses (except for resource previews). The codebeamer Server also supports rdf+xml as per OSLC Core Version 3.0 specification.

Accessing codebeamer Requirements Using the codebeamer Server

The codebeamer Server supports the following URI with supported authentication for the discovery of the Service Provider Catalog:

GET <protocol scheme>://<server host name>:<server port number>/<context URI>/api/oslc/catalog

For example:

GET https://codebeamer:8080/cb/api/oslc/catalog

The codebeamer Server supports the following URI with supported authentication for the various Service Provider and Service Provider Catalog resources:

GET <protocol scheme>://<server host name>:<server port number>/api/oslc/catalog/projects

For example:

GET https://codebeamer:8080/cb/api/oslc/catalog/projects

Working with Queries

The codebeamer OSLC Server provides query capabilities as per the OSLC Core 3.0 specification. Using query capabilities, client applications such as Windchill can query or search for codebeamer resources in a project for the Requirements domain.

The client applications can navigate to the URIs for query capabilities through discovery of service provider catalogs and service provider resources provided by the codebeamer Server.

The OSLC client applications can discover the URIs of the query capabilities by sending GET request on a project to the codebeamer Server per the following URI:

GET <protocol scheme>://<server host name>:<server port number>/api/oslc/projects/<Project ID>

For example:

GET https://codebeamer:8080/cb/api/oslc/projects/3

The client applications must set the Accept header to application/rdf+xml as the content type in the GET requests to the codebeamer OSLC Server. The OSLC clients must also set the OSLC-Core-version header to 3.0 when sending the GET requests. The response for such GET request includes URIs for the query capabilities.

Query capability is supported for GET requests only.

For example, the codebeamer Server supports the following URI with supported authentication for the query capability corresponding to the codebeamer Requirement resources:

GET <protocol scheme>://<server host name>:<server port number>/api/oslc/projects/<Project ID>/rm/requirements

For example:

GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements

The following are some examples of OSLC query parameters for use with the query property attributes:

• oslc.where query parameter
  

  GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.where=dcterms:identifier=4
  
  GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.where=dcterms:title=Input
  

• oslc.orderBy query parameter
  

  GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.orderBy=dcterms:identifier
  

The default sort order is ascending.

To request descending sort order, the request URI is as follows:

GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.orderBy=-dcterms:identifier

• oslc.select query parameter
  

  GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.select=dcterms:identifier,dcterms:title
  

• oslc.pageSize query parameter
  

  GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.pageSize=25
  

• page query parameter

For example:

https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements?oslc.where=dcterms:title=req&oslc.select=dcterms:identifier,dcterms:title&oslc.orderby=-dcterms:identifier&oslc.pageSize=25&page=2

You can create queries using codebeamer fields as per the table in Mapping the Requirements Management Domain.

Query capability is supported for a single filter criterion. The AND and OR operators are not supported. Only the = logical operator is supported.

Accessing a specific requirement

You can access a specific requirement as follows:

GET <protocol scheme>://<server host name>:<server port number>/api/oslc/projects/<Project ID>/rm/requirements/<Requirement ID>

For example:

GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements/101

Working with Resource Shapes

Resource shapes specify a standard way of describing resources and constraints on resources. For more information on resource shapes, refer to the OSLC specification.

The codebeamer server is resource-shape compliant.

A sample resource shape URI for the requirement resource is as follows:

GET  https://codebeamer:8080/cb/api/oslc/ns/rm/1.0/Requirement

Allowed values are not currently supported.

Working with Resource Previews

The codebeamer Server supports compact resources that describe how the previews of the resources for the Requirements domain can be located. The server provides HTML markups that OSLC client applications can use to display a small preview. Resource Previews allow you to view the information and additional metadata related to the resources quickly without leaving the OSLC client application such as Windchill.

Requesting Compact Resources Using Headers

The codebeamer Server supports compact representation for preview of codebeamer resources. The server provides URIs for small preview, icons, ID, and title of the codebeamer resources when an OSLC client application such as Windchill requests discovery of compact resources.

The codebeamer Server provides support for compact resources as per the Header of the requests received from the OSLC client applications. OSLC client applications can send a GET request with the following headers for discovering compact resources:

• Accept Header
• Link Header

Accept Header

If the codebeamer Server receives a GET request for a resource from the OSLC client application with the Accept header specified as application/x-oslc-compact+xml, the response for such GET request includes application/x-oslc-compact+xml as the content type for the Accept header. This indicates that the client has requested compact representation for a resource.

The codebeamer Server supports application/x-oslc-compact+xml as the content type for allowing OSLC client applications to use content negotiation to access the Compact resource, as per OSLC Core Version 2.0.

To discover compact resources using the Accept header, OSLC client applications can use the HTTP Accept header with the application/x-oslc-compact+xml content type for requesting the Compact resource representation for a URI. The client application must set the Accept Header with value as application/x-oslc-compact+xml when sending the GET request.

The codebeamer OSLC server provides compact resources for the supported resources, in the body of the response of such requests. The compact resources are provided in the rdf+xml content type.

Link Header

If the codebeamer Server receives a GET request for a resource from the OSLC client application with value of the Accept header specified as application/x-oslc-compact+xml, the response for such GET request includes application/x-oslc-compact+xml as in the rdf+xml content type and includes the Link header. The value of the Link header in the response provides the following:

• Target URI of the compact resource

For example:

GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements&compact

• Link relation (http://open-services.net/ns/core#Compact)

This indicates that compact representation is available for the specified resource.

For example:

<https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements&compact>; rel="http://open-services.net/ns/core#Compact"

The OSLC client application must then send a GET request to the codebeamer OSLC Server using the target URI of the compact resource for discovering the small preview.

For example:

GET https://codebeamer:8080/cb/api/oslc/projects/3/rm/requirements&compact

The OSLC client application must specify the content type for the response using the Accept header when sending the GET request with the target URI. The codebeamer Server supports application/rdf+xml as the content type for such request responses.

Accessing Resource Previews

Resource previews provide small preview information of the codebeamer resources for supported domains. The codebeamer Server provides the resource URI that the OSLC client applications such as Windchill can use to discover the link label and a resource icon. The OSLC client applications can then use the link label and icon to display the link in a meaningful way.

The codebeamer Server supports the following URI with supported authentication for displaying the small preview of the codebeamer resources:

GET <protocol scheme>://<server host name>:<server port number>/oslc-preview/projects/<Project ID>/rm/requirements/<Requirement ID>/preview.spr?preview=small

For example (rich preview):

GET https://codebeamer:8080/oslc-preview/projects/3/rm/requirements/1014/preview.spr?preview=small

For example (basic preview):

GET https://codebeamer:8080/oslc-preview/projects/3/rm/requirements/1014/basic/preview.spr?preview=small

Working with External Linked Items

The codebeamer Server has the ability to look up external linked items and provide information about the codebeamer resources linked with the external systems such as Windchill. The OSLC client applications can query for the codebeamer resources associated with the specified resource exposed by Windchill. In response to such a query, the codebeamer Server provides information about external linked items associated with the specified resource of Windchill.

Viewing codebeamer Resources with Lookup for External Linked Items

The codebeamer Server supports the following URI with supported authentication for the lookup for external linked items:

GET <protocol scheme>://<server host name>:<server port number>/<context URI>/links/traceLinkResources

For example:

GET https://codebeamer:8080/cb/api/oslc/links/traceLinkResources

The following query parameters are supported:

• oslc.where
• oslc.select
• oslc.pageSize
• page

https://codebeamer:8080/cb/api/oslc/links/traceLinkResources?oslc.where=cb:traceLinkTargetURI=https://pwdcsv-wcqa54d.ptcnet.ptc.com/Windchill/oslc/config/parts/VR%3Awt.part.WTPart%3A122505 

The codebeamer Server provides information of the codebeamer resources that are associated or linked with the specified parts of Windchill. The response also includes the URI of the codebeamer resources under the cb:infoPage field for opening the items in codebeamer.

The codebeamer Server provides information only for the supported codebeamer Requirement tracker items in the response for the reverse lookup query.