The following is a step-by-step guide to building a genOSLC based integration to your authoring tool.

1) Select domain and resource types for your authoring tool

Specify which OSLC domain or domains and resource types will be supported by your integration. 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 https://smartfacts.atlassian.net/wiki/pages/createpage.action?spaceKey=SPD&title=Application.YML&linkCreation=true&fromPageId=66125859, as seen below.

smartfacts:
  genoslc:
    oslc-domains:
      # OSLC domain supported by this integration
      - domain: http://open-services.net/ns/qm# 
        
        types: [
          { 
            # OSLC resource type
            type: "http://open-services.net/ns/qm#TestCase",
            
            # Custom label for this type of resource e.g. "My Test Case"
            label: "Test Case" }
        ]

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.

If your authoring tool will be storing links then your IToolAdapter interface must implement the following method:

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

2) Define conceptual mapping between OSLC type and the types in your authoring tool

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 https://smartfacts.atlassian.net/wiki/pages/createpage.action?spaceKey=SPD&title=Application.YML&linkCreation=true&fromPageId=66125859. 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, work item etc.

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

ResourceShape

A ResourceShape represents a the scheme or type of a resource. Essentially it is a list of attributes that are expected on the artifact which it represents.

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

3) Deploy 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.

4) Transform the example application to retrieve data from your authoring tool.

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

5) 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.

Smartfacts Public Documentation

genOSLC Steps to build an Integration