1 Accessing the genOSLC Source Code
2 Building and running the genOSLC example
3 Running the genOSLC Example
4 Example domain resource
- 4.1 Link storage
5 Mapping between OSLC and Example Types
- 5.1 Service Provider
- 5.2 Component
- 5.3 Artifact
- 5.4 ResourceShape
6 Accessing, Building and Running the example application and plugin in your infrastructure
7 IToolAdapter example implementation
8 Create Resource Preview and other delegated UI elements
- 8.1 Resource Preview
- 8.2 Selection Dialog
- 8.3 Creation Dialog
- 8.4 Link Index
- 8.5 Link Validity

The following is a description of the genOSLC Example Application including how to build, run and use the application as well as details on its implementation. This example application may be cloned and used as a template for building new OSLC connectors. See genOSLC Steps to build an Integration for details on how to do so.

Accessing the genOSLC Source Code

The genOSLC framework and example source code is part of the OSLC GitLab Projects at https://gitlab.mid.de/smartfacts/oslc:

https://gitlab.mid.de/smartfacts/oslc/genoslc-framework - the GitLab repo for the genOSLC framework. This must be instantiated to create a server implementation
https://gitlab.mid.de/smartfacts/oslc/genoslc-example - the GitLab repo for the genOSLC example, an instantiation of the genOSLC framework demonstrating how the framework is used. Can be used as a template for creating new connectors.

For genoslc-framework, there are only two branches, develop (default) and main. As of 17-July-2025, main was last updated 26-June: prepare for next development iteration, version 1.0.40.

For genoslc-example, the last update was 22-May-2025 to update the springdoc version. It only has one branch, main (default).

Checkout these two repos to get the genOSLC framework and source code.

Building and running the genOSLC example

See: Setting up your IDE for how to setup IntelliJ to be able to build and run the genOSLC example. This maven settings.xml file needs to be added to your ~/.m2 folder.

The genOSLC example uses a MongoDB database for persistence. While it is possible to manually install and configure a MongoDB instance to use for the example, it is much easier to compose the Docker image using IntelliJ:

Composing the deployment image results in the MongoDB database at mongodb://localhost:27017.

Build the genOSLC example with the InteliJ project:

Or use:

mvn install

Running the genOSLC Example

The application.yml file in the genoslc-example repo is a template for the genOSLC framework configuration. See the application-local.yml profile for an instantiation of this template that provides information needed to run the example within the MID execution environment. MID internal developers can copy this content as a local file in their genoslc-example project.

Click on the run button in IntelliJ to run the genOSLC example, ExampleMain:

The MongoDB database will be automatically created and populated with sample data.

The smartfacts.genoslc.public-uri in the application-local.yml profile is https://genoslc:8443 which can be used to access the example UI.

Example domain resource

The oslc-domainselement in the application.yml file specifies the OSLC domains and resources supported by the application. The genOSLC example supports QM test cases, RM requirements, CM change requests, and AM resources.. See: OSLC Specifications. These domains and types must be listed in the genOSLC metamodel which may be extended see:genOSLC Metamodel. The metamodel is used to determine which links may be created between resources.

Specify the OSLC domains and resource types that are supported by your authoring tool in Application.YML, as seen below.

smartfacts:
  genoslc:
    oslc-domains:
      - domain: http://open-services.net/ns/qm#
        types: [ { type: "http://open-services.net/ns/qm#TestCase",
                   label: "Test Case" } ]

      - domain: http://open-services.net/ns/rm#
        types: [ { type: "http://open-services.net/ns/rm#Requirement",
                   label: "Requirement" } ]

      - domain: http://open-services.net/ns/cm#
        types: [ { type: "http://open-services.net/ns/cm#ChangeRequest",
                   label: "Issue" } ]

      - domain: http://open-services.net/ns/am#
        #        abbreviation: "EXM" # this defaults to abbreviation in the metamodel
        types: [ { type: "http://open-services.net/ns/am#Resource",
                   label: "Architecture Element" } ]

The OSLC resource type, and OSLC domain must be present in the metamodel (either the default metamodel or a custom metamodel).

Link storage

Depending on the metamodel and the domain(s) that you have chosen you may need to be able to store created links in your application. Generally links in OSLC are only stored in only one of the two applications - in the logically dependent resource. e.g. when a test case validates a requirement, the test case is dependent on the requirement and thus stores the link to the requirement.

The genOSLC example does store links and its IToolAdapter interface implements the following method:

 public interface IToolAdapter {
 // ...
 void updateArtifactLinks(@NonNull String componentId,
                          @NonNull String localConfigurationId,
                          @NonNull String artifactConceptId,
                          @NonNull Set<LinkTao> links);
//...
}

Mapping between OSLC and Example Types

genOSLC provides a class model for important OSLC types see: Tool Adapter Objects and IToolAdapter Implementation. This model must mapped to concepts in your authoring tool.

Service Provider

A Service Provider represents a grouping of resources often belonging to a particular project, or program. The Service Provider is often mapped to concepts such as ‘Project’, or ‘Project Area’. The Service Provider owns a group of Components.

Component

A Component is the smallest configurable container in OSLC. Configurable means ability to have branches, streams, and or baselines. The primary purpose of a component is to be a container of resources - both artifacts and scheme resources.

A component is often mapped to an individual document or configurable group of documents. The following are example of objects which might be represented as a component.

Codebeamer Tracker
Codebeamer Working Set
DOORS Classic Module
Microsoft Word document

An individual component may only belong to only one Service Provider.

In some authoring tools there is always one-to-one relationship between a Service Provider and a Component. When this is the case the following should be set in the Application.YML. This will allow genOSLC to provide a cleaner user interface.

smartfacts:
  genoslc:
    service-provider-component-singleton: true

Artifact

An Artifact represents a user created ALM resource e.g. requirement, test case, change request, etc.

An artifact must have an identifier that remains stable independent of changes to the artifact. See conceptId and revisionId for more information.

ResourceShape

A ResourceShape is used to define constraints on the domain vocabularies that is often used to represent a the schema or type system for resources. Essentially it is a list of attributes that are expected on the vocabulary term (RDF class) or artifact which it constrains.

An ResourceShape must have an identifier that remains stable independent of changes to the artifact. See conceptId and revisionId for more information.

Accessing, Building and Running the example application and plugin in your infrastructure

An example genOSLC application is provided: https://smartfacts.atlassian.net/wiki/pages/createpage.action?spaceKey=SD&title=genOSLC%20Example%20Application. Deploy this into your company’s infrastructure.

Implement/configure the example application so that it complies with your company’s security policy. It contains common example e.g. OIDC.
Configure the example application OAuth1.0a so that it communicates with Smartfacts or IBM ELM. See https://smartfacts.atlassian.net/wiki/pages/createpage.action?spaceKey=SPD&title=OAuth%201.0A&linkCreation=true&fromPageId=66125859 for more details.
Confirm that you can create and display links, contribute local configurations to local configurations, display hover preview, etc.

IToolAdapter example implementation

This involves transforming the example implementation of the IToolAdapter so that it retrieves data from your server.

Create Resource Preview and other delegated UI elements

The only required UI element for a genOSLC integration is a Resource Preview. These are expected to be displayed in an iframe in an external application. The selection and creation dialogs are optional.

Resource Preview

This is a small web application that shows a preview of one of your resources. It is most often displayed by an external application a user hovers over a link to one of your resources .

Selection Dialog

This allows an external application to select a resource in your application, with the purpose of creating a link to your application. This is not necessary for all integrations e.g. links are only created when in the user is in your application.

Creation Dialog

This allows an external application to create a new resource in your application (e.g. a change request). This is only rarely required.

genOSLC Example Application