This wiki is locked. Future workgroup activity and specification development must take place at
our new wiki
. For more information, see
this blog post about the new governance model
and
this post about changes to the website
.
TWiki
>
Main Web
>
CmHome
>
CmSpecificationV1
>
CmServiceDescriptionV1
(19 Nov 2009,
TWikiAdminUser
)
(raw view)
<h1 id="titleL2-community">Change Management Service Description</h1> _1.0 SPECIFICATION_ %RED% %ENDCOLOR% %TOC% ---++ Introduction Clients with a need to interact with a Change Management system need a mechanism for discovering its capabilities, and the URLs used to access those capabilities. There are several aspects to the discovery process. First, clients may need to discover the existence of the Change Management system itself. Once discovering that, clients will want to discover the contexts in which change requests may exist, often referred to as projects or user databases. Once identifying a context, the clients need to discover the services that are provided within that context. This portion of the OSLC CM spec addresses the latter two of these scenarios, leaving the discovery of the CM system itself to either manual configuration or a broader network configuration mechanism. Therefore, this spec focuses on how clients will discover a context (or project), the service document associated with that context, and the format of that document. ---++ Notation and Conventions The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [[http://www.ietf.org/rfc/rfc2119.txt][RFC2119]]. Domain name examples use [[http://tools.ietf.org/html/rfc2606][RFC2606]]. ---++ Terminology *Service Description Resource* - an informational resource describing the capabilities and contextual configuration needed for a set of change management-specific services. *Service Description Document* - the representation of a Change Management Services Resource. *Service Provider* - an implementation of the OSLC Change Management specifications as a server. OSLC CM clients consume these services ---++ Sevice Discovery Starting with a single entry point to a service provider {base-url}, 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 a CM service description document. The figure below illustrates a simple interaction where there is only one set of choices and then configuration has been completed <img alt="" src="file:///C:/DOCUME~1/ADMINI~1/LOCALS~1/Temp/moz-screenshot-8.jpg" /> The dicovery model flow is as follows: 1 Request information from an OSLC CM based service provider: GET {url} 1 If Response is a [[OslcServiceProviderCatalogV1][Service Provider Catalog]]: 1 An entry is selected from the Service Provider Catalog 1 With this entry's {url}, repeat to step #1 1 If Response is a Service Description Document, then continue to next step 1 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 Description Resource A Service Description Resource is an informational resource describing a the contextual configuration needs of a service provider. The GET method on a Service Description Resource MUST retrieve a Service Description Document. This specification only covers retrieving a Service Description Resource with GET. The behavior of POST, PUT, and DELETE methods on Service Description Resources are not covered in this specification. ---++ Service Description Document The Service Description Document provides configuration definitions needed by consumers of a service provider. The Service Description Document MUST be indentified using the media type of =application/x-oslc-cm-service-description+xml.= XML namespace abbreviations used in this specification: * =rdf= - [[http://www.w3.org/TR/rdf-syntax-grammar/][RDF XML]] namespace - =http://www.w3.org/1999/02/22-rdf-syntax-ns#= * =dc= - The [[http://dublincore.org/documents/dcmi-terms/][Dublin Core Metadata Terms]] namespace - =http://purl.org/dc/terms/= * =oslc_cm= - The [[CmHome][Open Services for Lifecycle Collaboration Change Management]] namespace - =http://open-services.net/xmlns/cm/1.0= / <table width="100%" cellspacing="0" cellpadding="0" border="1"> <tbody> <tr> <td colspan="3" valign="top"> *XML Representation Summary:* ServiceDescriptor *Element* </td> </tr> <tr> <td colspan="3" valign="top"><oslc_cm:ServiceDescriptor rdf:about="anyURI"> <br /> _Content_: {dc:title, dc:description?, dc:contributor?, oslc_cm:changeRequests}<br /> </oslc_cm:ServiceDescriptor> </td> </tr> <tr> <td valign="top"> *Property* </td> <td valign="top"> *Representation* </td> <td> *Presentable* <br /></td></tr> <tr> <td valign="top">dc:title</td> <td valign="top">The REQUIRED title string. Note that this element comes from the DC namespace, allowing tools unaware of the change management domain to access this element. </td> <td> Yes</td></tr> <tr> <td valign="top">dc:description</td> <td valign="top">The REQUIRED description string. This element comes from the DC namespace, allowing tools completely unaware of the change management domain to access this element. </td> <td> Yes</td></tr> <tr><td>dc:contributor</td><td>The OPTIONAL contributor string. This element comes from the DC namespace, defining the contributing entity of this service implementation. <br /></td><td> N/A</td></tr><tr><td> - dc:title</td><td>The OPTIONAL title string that could be used for display. <br /></td><td> Yes</td></tr><tr><td> - dc:identifier </td><td>The REQUIRED contributor identifier. This can be of any form but recommend to either be of URN com.{company name}.{product indentifier} or URL forms. This property is to be used by a client application to identify the provider of this service. <br /></td><td> No</td></tr><tr><td> - oslc_cm:icon</td><td>The OPTIONAL URL to an icon file that represents the provider. This icon should be a [[http://en.wikipedia.org/wiki/Favicon][favicon]] format and 16x16 pixels in size<br /></td><td> Yes</td></tr><tr> <td valign="top">oslc_cm:changeRequests version</td> <td valign="top">The REQUIRED changerequests element.</td> <td> No</td></tr> <tr><td>- oslc_cm:home <br /></td><td>The OPTIONAL home element when present it MUST have child elements <dc:title> and <oslc_cm:url>. This can be used by service providers to provide a URL to the main Web UI which clients may use to navigate to. There MUST only be one occurrence of this element. </td><td>Only <dc:title> <br /></td></tr><tr><td> - {oslc_cm:factory default=[true|false]}* <br /></td><td>The REQUIRED factory element with REQUIRED child elements <dc:title> and <oslc_cm:url>. There may be an optional <oslc_cm:label> element that is intended for use in a choice list.</td><td> Only <dc:title></td></tr><tr><td> - oslc_cm:simpleQuery</td><td>The REQUIRED simple query element with REQUIRED child elements <dc:title> and <oslc_cm:url>. There MUST be only one simpleQuery element.<br /></td><td> Only <dc:title><br /></td></tr><tr><td> - oslc_cm:selectionDialog default={true|false} hintWidth={width} hintHeight={width} </td><td>The REQUIRED selection dialog element with REQUIRED child elements of <dc:title> and <oslc_cm:url>. There MAY be more than one selectionDialog element. There may be an optional <oslc_cm:label> element that is intended for use in a choice list. The optional hintHeight and hintWidth attributes that allow the hosting application to define an initial size of the window to host the selection dialog, the valid values for these attributes is defined by the CSS 2 [[http://www.w3.org/TR/CSS2/visudet.html#the-width-property][width]] and [[http://www.w3.org/TR/CSS2/visudet.html#the-height-property][height]] attributes. </td><td><dc:title>, <oslc_cm:label><br /></td></tr><tr><td> - oslc_cm:creationDialog default={true|false} hintWidth={width} hintHeight={width}</td><td>The REQUIRED creation dialog element with REQUIRED child elements of <dc:title> and <oslc_cm:url>, used to retrieve a web form for the creation of new change request resources. There MAY be more than one creationDialog element. There may be an optional <oslc_cm:label> element that is intended for use in a choice list. The optional hintHeight and hintWidth attributes that allow the hosting application to define an initial size of the window to host the creation dialog, the valid values for these attributes is defined by the CSS 2 [[http://www.w3.org/TR/CSS2/visudet.html#the-width-property][width]] and [[http://www.w3.org/TR/CSS2/visudet.html#the-height-property][height]] attributes. </td><td><dc:title>, <oslc_cm:label></td></tr></tbody> </table> Providers of this Service Description Document MAY provide additional properties in a non-OSLC namespace. Presentable text is intended to be seen by users of the client application communicating with the provider of this service. Presentable text, as indicated in the table above, can have multiple entries per translated language supported. The language of each presentable text string will be indicated with the [[http://www.w3.org/TR/REC-xml/#sec-lang-tag][ =xml:lang= attribute]]. ---+++ Example <verbatim><?xml version="1.0" encoding="UTF-8"?> <oslc_cm:ServiceDescriptor xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/terms/" xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" rdf:about="http://example.com/bugs/service-descriptor.xml"> <dc:title>Project X</dc:title> <dc:description>My Product Name's OSLC CM Service Description for Project X.</dc:description> <dc:contributor> <dc:title>My Company Name, My CM Product</dc:title> <dc:identifier>com.mycompany.myproduct</dc:identifier> <oslc_cm:icon>../icons/myprod.ico</oslc_cm:icon> </dc:contributor> <oslc_cm:changeRequests version="1.0"> <!-- Resource creation factory URL --> <oslc_cm:factory oslc_cm:default="true"> <dc:title>Location for creation of bugs</dc:title> <oslc_cm:url>./bug</oslc_cm:url> </oslc_cm:factory> <!-- Alternate resource creation factory URL --> <oslc_cm:factory> <dc:title>Location for creation of *HIGH PRIORITY* bugs</dc:title> <oslc_cm:url>./bug?priority=High</oslc_cm:url> </oslc_cm:factory> <!-- Simple GET-based URL-encoded query --> <oslc_cm:simpleQuery> <dc:title>Simple GET-based Bug Query</dc:title> <oslc_cm:url>./bugsquery</oslc_cm:url> </oslc_cm:simpleQuery> <!-- Resource Selection Dialog --> <oslc_cm:selectionDialog oslc_cm:hintWidth="740px" oslc_cm:hintHeight="480px"> <dc:title>Web Dialog for finding and selecting bugs.</dc:title> <oslc_cm:url>./ui/resourcePicker</oslc_cm:url> </oslc_cm:selectionDialog> <!-- Resource Creation Dialog --> <oslc_cm:creationDialog oslc_cm:hintWidth="600px" oslc_cm:hintHeight="320px"> <dc:title>Bug Submit Dialog for creating bugs.</dc:title> <oslc_cm:label>Bug</oslc_cm:label> <oslc_cm:url>./ui/submitDialog</oslc_cm:url> </oslc_cm:creationDialog> </oslc_cm:changeRequests> </oslc_cm:ServiceDescriptor> </verbatim> ---++ References * [[http://www.opensearch.org/Specifications/OpenSearch/1.1][OpenSearch 1.1]] * [[http://www.w3.org/TR/REC-xml/#sec-lang-tag][W3C XML 1.0 - xml:lang]] * [[http://dublincore.org/documents/dcmi-terms/][Dublin Core Metadata Terms]]
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r33
<
r32
<
r31
<
r30
<
r29
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r33 - 19 Nov 2009 - 21:12:56 -
TWikiAdminUser
Main.CmServiceDescriptionV1 moved from Main.CmServiceDescription on 28 May 2009 - 14:15 by
ScottBosworth
-
put it back
Main
Main Web
Create New Topic
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
Webs
Main
Sandbox
TWiki
Български
Cesky
Dansk
Deutsch
English
Español
Français
Italiano
日本語
Nederlands
Polski
Português
Русский
Svenska
简体中文
簡體中文
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our
Terms of Use
Ideas, requests, problems regarding this site?
Send feedback