1. Outline

The OSLC Configuration Management specification is a reference for servers that want to expose configuration management to OSLC clients. However, the specification is not organized as a tutorial or introduction about how to implement an OSLC configuration management compliant server or adapter.

This primer serves as a guide to the concepts in the specification, and through the use of simple examples, explains how versioning and configurations are represented, how and when local configurations and global configurations are used, and lists the elements that an implementation should consider. The specification remains the definitive source, and where this primer differs from the specification, the specification should be taken as the authoritative reference.

2. Motivation

3. Concepts

Configuration Management on Wikipedia defines Configuration Management as follows:

Configuration management (CM) is a systems engineering process for establishing and maintaining consistency of a product’s performance, functional, and physical attributes with its requirements, design, and operational information throughout its life.

In Configuration Management, artifacts are versioned. For example, a new requirement R1 might be defined and created. Once the content of that requirement is checked in or committed, version 1 of that requirement R1 exists. At that point, the contents of version 1 cannot be changed. If changes are required, the content is changed, and when checked in or delivered, results in version 2 of requirement R1. Version 2 of R1 was created from, or derived from, version 1 of R1. The sequence of versions of that requirement comprise its version history. In OSLC Configuration Management, the term concept resource is used to mean all the versions of some artifact. In our example, requirement R1 is a concept resource (no version is specified), and requirement R1 version 1 is a specific version of that concept resource. Many versioning systems exist, and there are a number of different approaches as to how artifacts are versioned, when those versions are created, and when a version becomes non-modifiable. However, all versioning systems support some notion of when a change is committed, the version that records that change becomes non-modifiable. The OSLC Configuration Management specification does not define how versioning should be implemented. For example, some versioning systems assign version identifiers separately for each versioned resource, while other versioning system version an entire repository so that a version identifier is “global” across all versioned resources. Servers are free to choose existing versioning systems, or implement a versioning system of their own design.

An important element of Configuration Management is a configuration. A configuration defines what set of version resources are used in that configuration. For example, configuration C1 might use version 1 of requirement R1, and configuration C2 might use version 2 of requirement R1. New artifacts might be added to or obsolete artifacts removed from a configuration. The configuration therefore provides a view of the appropriate artifacts and versions of those artifacts that apply in that configuration. The OSLC Configuration Management specification defines this in terms of selections. A configuration might reference a selections resource that in turn references the specific version resources that belong in that configuration.

In OSLC Configuration Management, a stream is a modifiable configuration in which artifacts may be added or removed, or a different version of an artifact may be selected by a user to replace some other version of that artifact. Streams are the configurations in which ongoing work is performed. An essential element of Configuration Management is the ability to create a non-modifiable record of the set of version resources at specific milestones or points in time in order to provide traceability and auditing. In OSLC Configuration Management, a baseline is a non-modifiable configuration whose set of version resources are also non-modifiable. Usually a baseline is created from a stream, recording the state of that stream. The stream continues to be modifiable, but the baseline is now a non-modifiable record of the state of the stream at the time the baseline was created. Every configuration is associated with a component. A component is a unit of organization consisting of a set of version resources. When a baseline is created from a stream, both the baseline and the stream are for the same component. The granularity of a component is up to an application designer.

OSLC Configuration Management supports the idea that a configuration may be a container of other configurations. The term contribution describes a resource that has both a contribution order property and a reference to a configuration that is used by a parent configuration. Strictly speaking, the term contribution means a contribution resource, but is sometimes used informally as a shorthand for child configuration which is a contributed configuration. Configurations may thus form a hierarchy of configurations. The term global configuration is used to describe a configuration that aggregates configurations, especially those from other configuration management servers. For example, a global configuration might have contributions from a requirements management server, a quality management server, and a source code control server. The global configuration thus represents the state of version resources across those application servers.

There is a UML class diagram in section 7 that describes how these concepts, and those in following sections, relate to the resources described in the OSLC Configuration Management Specification.

4. Representation of version resources

We will use an example of two requirements, A and B, in order to explain some of the concepts and representations. From a concept resource point of view, one might think of the requirements as having some basic properties as shown below. Requirement B refines requirement A.

Requirement_a
    id: a
    name: "Requirement A"
    description: "A description of requirement A"


    Requirement_b
    id: b
    name: "Requirement B"
    description: "A description of requirement B"
    refines: Requirement_a

Let’s look at a possible RDF representation of requirement A version 1 (requirementA-v1). The RDF graph of requirementA-v1 might look something like:

:requirementA-v1
        a oslc_config:VersionResource ;
        dcterms:isVersionOf :requirementA .
    :requirementA
        a oslc_rm:Requirement ;
        oslc_config:versionId "v1" ;
        oslc_config:component :rmComponent1 ;
        dcterms:identifier "A" ;
        dcterms:title "Requirement A"^^rdf:XMLLiteral ;
        dcterms:description "A description of requirement A version 1"^^rdf:XMLLiteral .

There are two important things to note:

1. The main properties of the requirement are made using a subject URI of the concept resource :requirementA and not the URI of the specific version :requirementA-v1. This is done so that the same subject is used for properties of all the versions of that concept resource. A query against the concept URI :requirementA and dcterms:description would give the descriptions of requirement A across all versions.
2. There are a few statements made using the subject URI of the version resource :requirementA-v1 that specify the artifact is a version resource and its concept resource.

Now consider that requirement A has been updated with a new description, resulting in version 2 (requirementA-v2):

:requirementA-v2
        a oslc_config:VersionResource ;
        dcterms:isVersionOf :requirementA ;
        prov:wasRevisionOf :requirementA-v1 .
    :requirementA
        a oslc_rm:Requirement ;
        oslc_config:versionId "v2" ;
        oslc_config:component :rmComponent1 ;
        dcterms:identifier "A" ;
        dcterms:title "Requirement A"^^rdf:XMLLiteral ;
        dcterms:description "A description of requirement A version 2 (changed description)"^^rdf:XMLLiteral .

The statements using subject URI :requirementA-v2 include prov:wasRevisionOf :requirement-v1, indicating that version 2 was derived from or created from version 1 of requirement A. The dcterms:description of the concept resource specifies the changed description for version 2.

Similarly, one might have requirement B version 1 (requirementB-v1):

:requirementB-v1
        a oslc_config:VersionResource .
        dcterms:isVersionOf :requirementB .
    :requirementB
        a oslc_rm:Requirement ;
        oslc_config:versionId "v1" ;
        oslc_config:component :rmComponent1 ;
        dcterms:identifier "B" ;
        dcterms:title "Requirement B"^^rdf:XMLLiteral ;
        dcterms:description "A description of requirement B version 1"^^rdf:XMLLiteral ;
        oslc_rm:refines :requirementA.

Note that the oslc_rm:refines link is to the concept resource of requirement A :requirementA and not to a version of that requirement. While an implementation could link to a specific version resource, that’s usually undesirable. Consider what would happen if requirementB-v1 referenced requirementA-v1. When version 2 of requirement A is created, one might want requirement B to reference it. This would require that a new version 2 of requirement B be created in order to update that link. This results in a lot of new versions because the links themselves are referencing specific versions. If the link references the concept resource, the resolution of which version of requirement A is referenced, is decoupled and deferred. A user that views requirements A and B in a particular configuration context will see the versions of both requirements resolved in that configuration context. If requirement A was updated to version 2 in that context, then requirementB-v1 will have a refines link that now resolves to requirementA-v2. This avoids the need to update requirement B to reference that new version of requirement A.

Typically applications provide some means for a user to select their configuration context in their user interface. For work in progress, this is usually a stream. If the user wants to see the versions of artifacts that were used at an important milestone, they would typically select the baseline that was created for that milestone. From a REST API standpoint, a configuration context can be specified using either a Configuration-Context header or a oslc_config.context parameter in the request.

5. Local configurations

A configuration created in and used by an application to manage the selected versions in that configuration is called a local configuration. Using the previous example based on requirements, let’s imagine we have a stream in a requirements management application that selects requirements requirementA-v1 and requirementB-v1. The RDF representation of that stream might be as follows:

:rmStream1
        a oslc_config:Stream ;
        dcterms:title "First requirements management stream"^^rdf:XMLLiteral ;
        oslc_config:component :rmComponent1 ;
        oslc_config:selections :rmStream1Selections ;
        oslc_config:acceptedBy oslc_config:Configuration .

A configuration always has a component. The stream references zero, one, or more selections resource(s) that specify what version resources are selected by the stream. In our example, the selections resource might be as follows:

:rmStream1Selections
        oslc_config:selects :requirementA-v1, :requirementB-v1 .

A user might want to capture the state of that stream by creating a baseline. The RDF representation of such a baseline might be as follows:

:rmBaseline1
        a oslc_config:Baseline;
        dcterms:title "First requirements management stream (first baseline)"^^rdf:XMLLiteral ;
        oslc_config:component :rmComponent1 ;
        oslc_config:selections :rmBaseline1Selections ;
        oslc_config:baselineOfStream :rmStream1 ;
        oslc_config:acceptedBy oslc_config:Configuration .

The oslc_config:baselineOfStream property specifies the stream that the baseline was created from. The selections resource referenced by that baseline might be as follows:

:rmBaseline1Selections
        oslc_config:selects :requirementA-v1, :requirementB-v1 .

Creating that baseline from the stream results in that stream’s representation including an [updated] oslc_config:previousBaseline property:

:rmStream1
        a oslc_config:Stream ;
        dcterms:title "First requirements management stream"^^rdf:XMLLiteral ;
        oslc_config:component :rmComponent1 ;
        oslc_config:selections :rmStream1Selections ;
        oslc_config:acceptedBy oslc_config:Configuration ;
        oslc_config:previousBaseline :rmBaseline1 .

When requirement A was changed to create version 2, the stream rmStream1 would be updated to select that version:

:rmStream1Selections
        oslc_config:selects :requirementA-v2, :requirementB-v1 .

The baseline rmBaseline1 continues to select :requirementA-v1 and :requirementB-v1. The selections of a baseline cannot be modified. The baseline therefore serves as a non-modifiable record of the state of the stream from which it was created at a specific point in time.

6. Global configurations

A global configuration is a configuration used to assemble other configurations (typically from other application servers) into a hierarchy. To understand the usage, let’s consider that we have a quality management application that has a test case testCaseA that validates requirementA. Version 1 of that test case might have an RDF representation as follows:

:testCaseA-v1
        a oslc_config:VersionResource ;
        dcterms:isVersionOf :testCaseA ;
    :testCaseA
        a oslc_qm:TestCase ;
        dcterms:title "Test case validating requirement A"^^rdf:XMLLiteral ;
        dcterms:description "Details of how the test case validates requirement A"^^rdf:XMLLiteral ;
        oslc_qm:validatesRequirement :requirementA .

In this example, the quality management application has its own local stream that selects testcaseA-v1:

:qmStream1
        a oslc_config:Stream ;
        dcterms:title "First quality management stream"^^rdf:XMLLiteral ;
        oslc_config:component :qmComponent1 ;
        oslc_config:selections :qmStream1Selections ;
        oslc_config:acceptedBy oslc_config:Configuration .

with its referenced selections resource:

:qmStream1Selections
        oslc_config:selects :testCaseA-v1 .

A user looking at test cases in the context of configuration qmStream1 would see testCaseA-v1. That test case has a validates requirement link to requirement A. However, in that configuration context, it is not possible to resolve the link to a version of the requirement concept resource because that is managed by the requirement management application and not the quality management application.

This is where a global configuration is useful. As an example, say we have a global stream that has contributions from rmStream1 and qmStream1. Its RDF representation might be as follows:

:globalStream1
        a oslc_config:Stream ;
        dcterms:title "First global stream"^^rdf:XMLLiteral ;
        oslc_config:accepts oslc_config:Configuration ;
        oslc_config:acceptedBy oslc_config:Configuration ;
        oslc_config:contribution :contribution1, :contribution2 .
    :contribution1:
        oslc_config:configuration :rmStream1 ;
        oslc_config:contributionOrder "1" .
    :contribution2:
        oslc_config:configuration :qmStream1 ;
        oslc_config:contributionOrder "2" .

A user is working in the configuration context globalStream1. In the requirements management application, when the user looks at the requirements for component rmComponent1, they see requirementA-v2 and requirementB-v1. The requirements management application resolves the component rmComponent1 in the context of global configuration globalStream1. The global configuration has only one contribution associated with rmComponent1 and that’s for the local configuration rmStream1. That local configuration selects requirementA-v2 and requirementB-v1. Similarly, in the quality management application, when the user looks at the test cases for component qmComponent1, they see testCaseA-v1.

For that test case, the quality management user sees the validates requirement link to requirementA-v2. The quality management application only knows the link is to the test case concept resource requirementA and cannot resolve which version of that requirement is referenced. This is because the requirements management application that owns that requirement manages the configurations that select it. So how does the quality management application resolve the link to the requirement to a specific version?

When referencing that requirement, it uses a oslc_config.context query parameter or a Configuration-Context header with a value that is the URI of the configuration context. For example ":requirementA?oslc_config.context=':globalStream1'". The parameter value is shown here without URL encoding for clarity. In practice, parameter values should be URL encoded. When the requirements management application gets a request to fetch that requirement, it resolves the concept resource URI in the specified configuration context. In this example, it knows that the requirement concept resource requirementA is owned by component rmComponent1, and resolves that component in the global configuration context globalStream1 to the local configuration rmStream1, and then resolves the requirement concept resource requirementA to :requirementA-v2.

How does an application resolve a component in a global configuration context to a local configuration?

Say an RM application wants to resolve component rmComponent1 in the context of globalStream1. The starting point is to consider the hierarchy of the global configuration :globalStream1 and associated components. The previous example yields the tree shown below:

    globalStream1 (component=globalComponent1)
            rmStream1 (component=rmComponent1, order=1)
            qmStream1 (component=qmComponent1, order=2)

An application traverses this tree looking for component rmComponent1 and finds rmStream1. When the tree only contains a single configuration for a particular component, the order of traversal does not matter.

In practice, constructing a contribution tree by fetching data each time a component needs to be resolved to a local configuration does not scale well or provide the performance required for frequent resolution. Implementations commonly use some form of caching of that data and use an implementation dependent way of maintaining that cached data.

Global configurations therefore fulfill two important functions:

• They allow a configuration context to be used across applications that allow an application to resolve their concept resources to the right versions.
• They allow links between concept resources in different applications to be viewed and navigated to the right versions of those artifacts in that configuration context.

The distinction between a local configuration and a global configuration is a fuzzy one. Consider a requirements management server that supports configurations that have contributions from other configurations in the same server but not other servers. Should such a configuration be called a local configuration or a global configuration? The distinguishing characteristics of a global configuration are that they are normally usable as contributions in any other global configuration and may use contributions from any local or global configuration. So such a configuration would be more accurately termed a local configuration even though it has contributions.

7. UML Class diagram

The UML class diagram below shows the main elements of the configuration management specification. It intentionally omits some relationships for the sake of clarity. The resource shapes in the specification remain the definitive reference.

Some key aspects of the representation are:

• The version resources selected by a configuration are determined using the property path oslc_config:selections/oslc_config:selects.
• The immediate contributed configurations to a configuration are determined using the property path oslc_config:contribution/oslc_config:configuration. Contribution resources are embedded within configurations.
• Global configurations often only have contributions and not selections.
• Local configurations often only have selections and not contributions.

8. Component skew and contribution order

Consider a global stream globalStream2 that has contributions from rmStream1, rmBaseline1, and :qmStream1 in that order. rmStream1 and rmBaseline1 are for the same component. Where a configuration hierarchy has contributions from two different configurations of the same component, this is called component skew.

Now consider the contribution tree for globalStream2:

    globalStream2 (component=globalComponent1)
            rmStream1 (component=rmComponent1, order=1)
            rmBaseline1 (component=rmComponent1, order=2)
            qmStream1 (component=qmComponent1, order=3)

When resolving the concept requirementA in the context of globalStream2, should this resolve to requirementA-v2 selected by rmStream1 or requirementA-v1 selected by rmBaseline1? The component skew is resolved by the order in which the contribution tree is traversed. If the traversal algorithm orders rmStream1 before rmBaseline1, then component rmComponent1 resolves to rmStream1, and the requirementA resolves to requirementA-v2.

The configuration management specification does not prescribe a traversal algorithm, but a common approach is to perform a depth-first, sibling ordered by contribution order second traversal. Consider the following configuration hierarchy:

    globalStream2 (component=globalComponent1)
            globalStream3 (component=globalComponent2, order=1)
                rmStream1 (component=rmComponent1, order=1)
            globalStream4 (component=globalComponent3, order=2)
                rmBaseline1 (component=rmComponent1, order=1)
                qmStream1 (component=qmComponent1, order=2)

A depth-first, sibling ordered by contribution order second traversal results in the following traversal order:

    globalStream2
        globalStream3
        rmStream1
        globalStream4
        rmBaseline1
        qmStream1

Note that the contribution order should be sorted as an ASCII string rather than being treated as a numeric string.

9. Branching

The OSLC Configuration Management specification does not define whether a versioning system should support branching and/or parallel versions, and if so how these are managed. Some versioning systems support branches as first-class objects, and there are actions to create branches. Some versioning system handling branching by copying data into different paths in the repository, referencing the shared artifacts. Other versioning systems regard branching as simply parallel versions, perhaps for different variants or purposes. Because of these different approaches, branching is not covered by the specification so that it remains implementable across a wider range of systems.

From an OSLC standpoint, clients create new versions of concept resources by a PUT on the concept URI with a configuration context specifying the stream that will be updated to use the new version. The version that was previously used in that stream is the predecessor version of the newly created version. For example, if :rmStream1 uses requirementA-v1, a new version requirementA-v2 might be created from it by a PUT requirementA?oslc_config.context=%3ArmStream1. If a client then requests a new version be created from requirementA-v1 in some other stream, an implementation that supports branching might create requirementA-v2.1 as a parallel version to requirementA-v2. An implementation that only supports linear versioning might fail the request.

Typically, parallel development for different branches or purposes is performed in separate streams. For example, parallel streams might be created from the same baseline in order to work on separate features for some release. The OSLC Configuration Management specification does not define any mechanisms for merging streams. However, a client can PUT merged content to the concept resource where the merged content has multiple prov:wasRevisionOf statements indicating the contents were merged from those predecessor versions.

10. Implementation elements

11. Concept resources and version resources

12. References

https://oslc-op.github.io/oslc-specs/specs/config/oslc-config-mgt.html