Server Guide
This guide provides details about the Open Services for Lifecycle Collaboration (OSLC) Server for Codebeamer.
Prerequisites
To read, understand, and execute the instructions in this guide, you need the following:
• Familiarity with OSLC standards and specifications when using the Codebeamer Server.
• Administrator permissions to perform activities such installations and configurations on the server that hosts Codebeamer.
• System administrator permissions in Codebeamer.
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
You do not require specific installation or configuration steps to install the 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.
The OSLC services are available when the Codebeamer server is running.
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 may 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. Sign in to Codebeamer as system administrator and click > .
2. Do one of the following steps:
◦ Add the following application configuration:
"contentSecurityPolicy" : {
"text" : "frame-ancestors <EXTERNAL_DPT_SERVER_BASE_URL1> <EXTERNAL_DPT_SERVER_BASE_URL2>"
},
 |
When listing multiple servers in the "contentSecurityPolicy" application configuration, separate them by using spaces.
|
◦ Or set the following environment variable:
CB_CORS_ALLOWED_ORIGINS=<EXTERNAL_DPT_SERVER_BASE_URL1>,<EXTERNAL_DPT_SERVER_BASE_URL2>
|
|
When listing multiple servers in the CB_CORS_ALLOWED_ORIGINS environment variable, separate them by using commas.
|
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 the following:
|
Codebeamer field
|
OSLC term
|
Data type
|
Can it be queried?
|
|---|---|---|---|
|
ID
|
dcterms:identifier
|
Integer
|
Yes
|
|
Name or Summary
|
dcterms:title
|
String
|
Yes
|
|
Description
|
dcterms:description
|
String/rich text
|
Yes
|
|
Submitted on/at
|
dcterms:created
|
DateTime
|
No
|
|
Modified on/at
|
dcterms:modified
|
DateTime
|
No
|
|
Type
|
cb:type
|
String
|
No
|
|
Status
|
cb:status
|
String
|
No
|
|
Business Value or Priority
|
cb:priority
|
String
|
No
|
This mapping cannot be altered or changed by the user. No field mapping configuration is required on the Codebeamer server.
Supported Security Schemes
The Codebeamer Server supports the Basic Authentication and the OAuth 2.0 security schemes.
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 Resources Using the Codebeamer Server
When accessing the Codebeamer server with the OSLC APIs, consider these key points related to the Codebeamer permissions:
• Project-level access—To access the initial stream ID or the custom stream ID of a project, you must be a member of that project.
• User group level—To execute OSLC API calls, you do not require the Rest / Remote API - Access permission at the user group level.
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:8443/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>/<context URI>/api/oslc/catalog/projects
For example:
GET https://codebeamer:8443/cb/api/oslc/catalog/projects
Identifying the Codebeamer Projects
The GET /api/oslc/catalog/projects endpoint returns the projects by the initial stream ID and custom stream IDs. For detailed information about working sets, refer to Working-Sets. And for more information about streams, see About Streams.
See the following example response:
<oslc:ServiceProviderCatalog rdf:about="https://codebeamer:8443/api/oslc/catalog/projects">
<dcterms:title rdf:parseType="Literal">PTC Codebeamer Projects Catalog</dcterms:title>
<dcterms:description rdf:parseType="Literal">PTC Codebeamer Projects Catalog</dcterms:description>
<oslc:serviceProvider>
<oslc:ServiceProvider rdf:about="https://codebeamer:8443/api/oslc/projects/9234">
<dcterms:title rdf:parseType="Literal">Automotive ISO 26262:2018 & ASPICE Template</dcterms:title>
</oslc:ServiceProvider>
</oslc:serviceProvider>
<oslc:serviceProvider>
<oslc:ServiceProvider rdf:about="https://codebeamer:8443/api/oslc/projects/15585">
<dcterms:title rdf:parseType="Literal">Automotive ISO 26262:2018 & ASPICE Template (CustomWorkingSet01)</dcterms:title>
</oslc:ServiceProvider>
</oslc:serviceProvider>
In the preceding response, note the following:
• The project has two stream IDs: 9234 and 15585.
• 9234 is the initial stream ID of the project. A project has always a initial stream ID.
• 15585 is the custom stream ID of the project.
• The name of the custom stream ID 15585 appears in the <dcterms:title> tag in this format: <project name><space>(<custom stream name>). For example, in the Automotive ISO 26262:2018 & ASPICE Template (CustomWorkingSet01) value, the custom stream name is CustomWorkingSet01.
Working with Queries
The Codebeamer OSLC Server provides query capabilities based on 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 a GET request on a project to the Codebeamer server using the following URI:
GET <protocol scheme>://<server host name>:<server port number>/api/oslc/projects/<Working Set ID>
For example:
GET https://codebeamer:8443/api/oslc/projects/9234
 |
You can get the list of the streams in a Codebeamer project by using the GET /v3/projects/{projectId}/all-working-sets Swagger V3 endpoint.
|
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/<Working Set ID>/rm/requirements
For example:
GET https://codebeamer:8443/api/oslc/projects/9234/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:8443/api/oslc/projects/9234/rm/requirements?oslc.where=dcterms:identifier=19534
GET https://codebeamer:8443/api/oslc/projects/9234/rm/requirements?oslc.where=dcterms:title=Input
• oslc.orderBy query parameter
GET https://codebeamer:8443/api/oslc/projects/9234/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:8443/api/oslc/projects/9234/rm/requirements?oslc.orderBy=-dcterms:identifier
• oslc.select query parameter
GET https://codebeamer:8443/api/oslc/projects/9234/rm/requirements?oslc.select=dcterms:identifier,dcterms:title
• oslc.pageSize query parameter
GET https://codebeamer:8443/api/oslc/projects/9234/rm/requirements?oslc.pageSize=25
|
|
The default page size is 25. The maximum supported page size is 500.
|
• page query parameter
For example:
https://codebeamer:8443/api/oslc/projects/9234/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 Requirement Items
You can access requirement items in a project as follows:
GET <protocol scheme>://<server host name>:<server port number>/api/oslc/projects/<Working Set ID>/rm/requirements
For example:
GET https://codebeamer:8443/api/oslc/projects/9234/rm/requirements
The response returns information of the requirement items in the <oslc_rm:Requirement> tag. For example:
<oslc_rm:Requirement rdf:about="https://codebeamer:8443/api/oslc/projects/7/rm/requirements/1953">
<oslc:instanceShape rdf:resource="https://codebeamer:8443/api/oslc/ns/rm/1.0/Requirement"/>
<oslc:serviceProvider rdf:resource="https://codebeamer:8443/api/oslc/projects/9234"/>
<cb:infoPage>https://codebeamer:8443/issue/1953</cb:infoPage>
<dcterms:identifier>1953</dcterms:identifier>
<dcterms:description><div class="wikiContent">
The item chosen for this example primarily equals the AUTOsar guided tour example Front Light Management. Whenever additional definitions were needed, information supporting clarification of safety related topics was added.</dcterms:description>
<dcterms:title>Front Line Management ECU</dcterms:title>
<dcterms:created>2025-05-05T05:54:55Z</dcterms:created>
<dcterms:modified>2025-05-05T05:54:55Z</dcterms:modified>
<cb:status>New</cb:status>
</oslc_rm:Requirement>
To access a specific requirement item, you can use the <dcterms> information as a dcterms:identifier parameter. For example:
GET https://codebeamer:8443/api/oslc/projects/9234/rm/requirements?oslc.where=dcterms:identifier=1953
|
|
If a referenced Codebeamer item is moved to a different project, the corresponding URI will change and become inaccessible. To fix this, the corresponding link must be recreated. To avoid the issue, avoid moving referenced items.
|
Accessing the Attachments of a Requirement
You can access the attachments of a Codebeamer requirement by following these steps:
1. Ensure to execute the API calls with a user that has the following tracker-level permissions in Codebeamer:
◦ Permission to view an item—Item - View Any or Item - View if Owner.
◦ Permission to view the attachments of an item—Item - View Comments/Attachments.
2. Send an OPTIONS request to the /api/oslc/projects/{projectId}/rm/requirements/{requirementId} endpoint. For example:
OPTIONS https://codebeamer:8443/api/oslc/projects/3/rm/requirements/1002
3. Find the value of the Link response header. For example:
<http://www.w3.org/ns/ldp#Resource>; rel="type", <https://codebeamer:8443/api/oslc/projects/3/rm/requirements/1002/attachments>; rel=http://open-services.net/ns/core#AttachmentContainer
4. Send a GET request to the /api/oslc/projects/{projectId}/rm/requirements/{requirementId}/attachments URL that appears in the value of the preceding Link response header for the oslc:AttachmentContainer. For example:
GET https://codebeamer:8443/api/oslc/projects/3/rm/requirements/1002/attachments
5. Find the <oslc: Attachmentcontainer> XML element in the response body. This contains one or more <ldp:contains> properties with a /api/v3/attachments/{attachmentId}/ content resource URL. For example:
<oslc: AttachmentContainer rdf:about="https://codebeamer:8443/projects/{projectId}/rm/requirements/1002/attachments>
[...]
<ldp:contains rdf :resource="https://codebeamer:8443/api/v3/attachments/4392/content"/>
|
|
The Attachment API does not support the functionalities related to the query parameters.
|
6. Use the {attachmentId} of the <ldp:contains> resource URL to get the content of the attachment with the Codebeamer GET /v3/attachments/{attachmentId}/content Swagger V3 endpoint. For example:
GET https://codebeamer:8443/api/v3/attachments/4392/content
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:8443/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 with the Accept header set to application/x-oslc-compact+xml, the response includes a compact resource in RDF/XML format and a 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:8443/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:8443/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:8443/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:8443/oslc-preview/projects/3/rm/requirements/1014/preview.spr?preview=small
For example (basic preview):
GET https://codebeamer:8443/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:8443/cb/api/oslc/links/traceLinkResources
The following query parameters are supported:
• oslc.where
• oslc.select
• oslc.pageSize
• page
For example:
https://codebeamer:8443/cb/api/oslc/links/traceLinkResources?oslc.where=cb:traceLinkTargetURI=https://testserver.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.