OSLC Service Discovery and Resource Definition DRAFT

NOTE: This is a work in progress

Overview

This intent of this specification is to identify how OSLC services are defined and can be discovered. It also will address the ability to locate a service resource, from any OSLC resource.

This will replace the Service Resources definition in the OSLC Core Spec DRAFT

Scenarios Supported

• Consumer has a single URL that describes enough configuration information to utilize a domain's services such as:
  • query
  • resource shapes
  • factories
  • delegated UIs
  • vendor info
  • authentication method
  • OSLC specs supported
• Service provider has multiple levels of contexts in which discovery needs to occur. A tool has a concept of products that contain projects, which is the final configuration end-point for services.
• A single service provider supports multiple OSLC domain specifications: Reporting and CM

Service Discovery Process

Starting with a single entry point to a service provider URI, clients will discover the (typically hierarchical) arrangement of contexts managed by the application. To support the wide range of application and project configurations, OSLC is not specifying a predetermined arrangement of these contexts. Instead, clients will be able to iterate through a group of collections (Service Provider Catalogs) until identifying a context of interest, where the client will find an OSLC service provider document.

The figure below illustrates a simple interaction where there is only one set of choices and then configuration has been completed

The discovery model flow is as follows:

1. Request information from an OSLC service provider:
2. If Response is a Service Provider Catalog:
   1. An entry is selected from the Service Provider Catalog
   2. With this entry's URI, repeat to step #1
3. If Response is a Service Description Document, then continue to next step
4. Configuration has completed

The number of iterations over the configuration choices should be set by the client application. Typical configurations should not need more than 2 levels of configuration context, so a limit of 5 is recommended.

Termination of the discover occurs when a the client application receives an HTTP response with a Content-Type of application/x-oslc-cm-service-description+xml and the service description document as the response's content body.

Service Context

Every OSLC Resource SHOULD have a reference to an resource that provides needed context. Often this will be an OLSC Resource that references it's OSLC Service Resource definition.

• Properties:
  • oslc:context (String, only-one) - brief title of the service.

Service Resources

OSLC services are available via a Service Resource which specifies the other resources that a client needs to interact with the service.

Conceptual Models

Resource: ServiceProvider?

This is the Service Provider Resource.

• Name: ServiceProvider
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc-core#
• Type URI: http://open-services.net/xmlns/oslc-core#ServiceProvider
• Properties:
  • dc:title (String, at-most-one) -
  • dc:description (String, at-most-one)) -
  • dc:contributor (Node of type oslc:Contributor, at-most-one)
  • oslc:context (anyURI, at-most-one)
  • Additional domain specific service entries

Node: Service

This is the Service Resource.

• Name: Service
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc-core#
• Type URI: http://open-services.net/xmlns/oslc-core#Service
• Properties:
  • oslc:version (String, at-most-one) - NOTE: perhaps this should be a URI
  • factory (Node of type oslc:Factory, zero-or-many) - a Service MAY have one or more creation capabilities.
  • query (Node of type oslc:Query, zero-or-many) - a Service MAY have one or more query capabilities.
  • selectionDialog (Node of type oslc:Dialog, zero-or-many) -
  • creationDialog (Node of type oslc:Dialog, zero-or-many) -
  • A Service Resource MAY provide other property values.

Node: Contributor

• Name: Contributor
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc-core#
• Type URI: http://open-services.net/xmlns/oslc#Contributor
• Properties: * dc:title (String, only-one) - title string that could be used for display * oslc:label (String, at-most-one) - very short label for use in menu items * dc:identifier (String, only-one) -This can be of any form but recommend to either be of URN com.{company name}.{product identifier} or URL forms. This property is to be used by a client application to identify the provider of this service. * oslc:icon (URL, only-one) - URL to an icon file that represents the provider. This icon should be a favicon format and 16x16 pixels in size * A Contributor Resource MAY provide other property values.

Node: Factory

• Name: Factory
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc-core#
• Type URI: http://open-services.net/xmlns/oslc#Factory
• Properties: * dc:title (String, only-one) - title string that could be used for display * oslc:label (String, at-most-one) - very short label for use in menu items * oslc:service (anyURI, only-one) - the URI of the factory service. * oslc:shape (Link, at-most-one) - a Factory Capability MAY provide Resource Shapes that describe the resources that can be created by the capability.
  • A Factory Capability MAY provide other property values.

Node: Query

• Name: Query
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc-core#
• Type URI: http://open-services.net/xmlns/oslc#Query
• Properties: * dc:title (String, only-one) - title string that could be used for display * oslc:label (String, at-most-one) - very short label for use in menu items * oslc:service (anyURI, only-one) - the URI of the query service. * oslc:shape (Link, at-most-one) - a Query Capability MAY provide Resource Shapes that describe the resources that can be created by the capability.
  • A Query Capability MAY provide other property values.

Node: Dialog

• Name: Dialog
• Suggested Prefix: oslc
• Namespace URI: http://open-services.net/xmlns/oslc-core#
• Type URI: http://open-services.net/xmlns/oslc#Dialog
• Properties: * dc:title (String, only-one) - title string that could be used for dialog title * oslc:label (String, at-most-one) - very short label for use in menu items * oslc:service (anyURI, only-one) - the URI of the dialog * oslc:hintWidth (String, at-most-one) - valid values for these attributes is defined by the CSS 2 width and height attributes. * oslc:hintHeight (String, at-most-one) - valid values for these attributes is defined by the CSS 2 width and height attributes. * There MAY be other property values.

Domain Definition

Domain specifications the define their services SHOULD define a property of Resource ServiceProvider? for their domain of type http://open-services.net/xmlns/oslc-core#Service

Delegated Service Picker

Since this function could easily be abstracted by a service provider, it would be possible to delegate the presentation of a Web UI to allow for service discovery.

TBD Currently no specs have this but would be desirable. This could be a node in either ServiceProvider? or ServiceProviderCatalog?

Service Provider Catalog

Service Provider Catalogs can either be nested with other Catalogs or can contain Service Provider resources. See OslcServiceProviderCatalogV1

Samples

1 provider, supporting 2 specifications (CM 2.0 and Reporting 2.0)

<?xml version="1.0" encoding="UTF-8"?>
<oslc:ServiceProvider xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/terms/" 
   xmlns:oslc="http://open-services.net/xmlns/1.0/"
   xmlns:oslc_cm="http://open-services.net/xmlns/cm/2.0/"
   xmlns:oslc_re="http://open-services.net/xmlns/reporting/2.0/"
   rdf:about="http://example.com/bugs/service-descriptor.xml"
   xml:lang="en">

   <dc:title>Project X</dc:title>
   <dc:description>My Product Name's OSLC CM and Reporting Service Description for
      Project X.</dc:description>
   <dc:contributor>
      <oslc:Contributor>
         <dc:title>My Company Name, My ALM Product</dc:title>
         <dc:identifier>com.mycompany.myproduct</dc:identifier>
         <oslc:icon rdf_resource="http://example.com/icons/myprod.ico" />
      </oslc:Contributor>
   </dc:contributor>
   
   <oslc:context rdf:resource="http://example.com/catalog" />

   <oslc_cm:changeRequests>
      <oslc:Service>
         <oslc:version>2.0</oslc:version>

         <oslc:factory>
            <oslc:Factory>
               <oslc:default>true</oslc:default>
               <dc:title>Location for creation of bugs</dc:title>
               <oslc:label>Bugs</oslc:label>
               <oslc:service>http://example.com/bugs</oslc:service>
               <oslc:shape rdf:resource="http://example.com/bugs/schema" />
            </oslc:Factory>
         </oslc:factory>

         <oslc:factory>
            <oslc:Factory>
               <dc:title>Location for creation of *HIGH PRIORITY* bugs</dc:title>
               <oslc:label>Bugs(High)</oslc:label>
               <oslc:service>./bug?priority=High</oslc:service>
               <oslc:shape rdf:resource="http://example.com/bugs/schema?priority=High" />
            </oslc:Factory>
         </oslc:factory>

         <oslc:query>
            <oslc:Query>
               <dc:title>Simple GET-based Bug Query</dc:title>
               <oslc:label>Bugs</oslc:label>
               <oslc:service>http://example.com/bugs</oslc:service>
               <oslc:shape rdf:resource="http://example.com/bugs/schema" />
            </oslc:Query>
         </oslc:query>

         <oslc:selectionDialog>
            <oslc:Dialog>
               <dc:title>Web Dialog for finding and selecting bugs.</dc:title>
               <oslc:label>Bugs</oslc:label>
               <oslc:service>http://example.com/bugs/ui/resourcePicker</oslc:service>
               <oslc:hintWidth>740px</oslc:hintWidth>
               <oslc:hintHeight>480px</oslc:hintHeight>
            </oslc:Dialog>
         </oslc:selectionDialog>

         <oslc:creationDialog>
            <oslc:Dialog>
               <dc:title>Bug Submit Dialog for creating bugs.</dc:title>
               <oslc:label>Bugs</oslc:label>
               <oslc:service>http://example.com/bugs/ui/submitDialog</oslc:service>
               <oslc:hintWidth>600px</oslc:hintWidth>
               <oslc:hintHeight>320px</oslc:hintHeight>
            </oslc:Dialog>
         </oslc:creationDialog>
      </oslc:Service>
   </oslc_cm:changeRequests>

   <oslc_re:reporting>
      <oslc:Service>
         <oslc:version>2.0</oslc:version>
         <oslc:query>
            <oslc:Query>
               <dc:title>Simple GET-based Bug Query</dc:title>
               <oslc:label>Bugs</oslc:label>
               <oslc:service>http://example.com/bugs</oslc:service>
               <oslc:shape rdf:resource="http://example.com/bugs/schema" />
            </oslc:Query>
         </oslc:query>
      </oslc:Service>
   </oslc_re:reporting>


</oslc:ServiceProvider>

References

• OslcServiceProviderCatalogV1?
• CmServiceDescriptionV1?
• RmServiceDescriptionV1?

Design Assumptions

• A single "service descriptor" can contain multiple domains
• A "service descriptor" can contain references to nested or other descriptors