Initial discovery (was: [oslc-core] OSLC & LDP: Query Capabilities, Creation Factories & location of Dialogs)

[Martin P Pain <martinpain@uk.ibm.com>]

This email is about how implementations (or instances
thereof) first interact with each other, concerning discovery of capabilities
and resources.

I've split this into three sections, but read it as
one continuous train of thought. I have other thoughts which I will send
in separate e-mails.


"One URL" configuration:
------------------------

Story:
As a user configuring an integration (e.g. system
administrator or project area administrator)
I want to configure the integration between two OSLC-enabled
servers/applications with as few steps as possible (e.g. providing a single
easily-available URL, plus any security config)
In order to have the full integration between those
two applications with minimal effort and confusion.

At the moment (in v2) OSLC does not seem to do anything
to suggest what that "one URL" should be. Something pointing
to a oslc:ServiceProviderCatalog might seem to be a good choice. However,
most IBM implementations (including mine) use the Jazz Root Services document
[1]. I believe the main motivation for this is that it is what the Jazz
products require, which is probably because they need the OAuth information
and this gives them a place to find it.

Steve, in your proposal, I expect this "one URL"
would point to a container, which can contain other containers to an arbitrary
depth to model the native hierarchy of the server.


Nesting of containers
---------------------

One benefit of the v2 structure is that clients know
how many levels of nesting to expect (as maximum). If we allow an arbitrary
amount of nested containers, not only is it further to navigate to find
out if there are really any resources of types of interest, but it's harder
to write a UI that can deal with the possible variation. In v2 UIs can
have a fixed number of drop-down lists or list boxes, but for arbitrarily-nested
containers, they would either need a tree (which isn't a simple component
for a web page) or be able to support a potentially infinite number of
drop-down list boxes, one for each level.

Perhaps that problem could be worked around by providing
a dialog on the root container to select the "leaf" containers
- those that contain resources of types other than "container".
but I don't think we could make that a MUST.
For headless/unattended operations, it would perhaps
make sense for them to require the URL of a "leaf" container,
but that means users need to be able to get hold of those URLs.

Story:
As a client implementor
I want to be able to write widely-interoperable code
for the intial discovery step with minimal effort
In order to quickly get going with OSLC and have code
that benefits from the loose-coupling of OSLC (rather than just having
coded for the one server to hand as the interoperable solution was too
hard)

Do you think we ought to have a term for these "leaf"
containers? Are they in any way special? In my mind they are different
from containers that only contain containers, because it seems to me that
they will be the primary resource that clients will be looking for (at
least during discovery).


Using URLs to web UIs in OSLC configuration
-------------------------------------------

Another problem is getting hold of that "one
URL". Users are generally only aware of the web UI URLs. While it
would be perfectly reasonable for any given implementation to perform content
negotiation on their web UI's homepage's URL to provide an RDF representation
of the server if an RDF media type was requested, I have come across people
unwilling to do that. (e.g. it means you can't stick that URL in a browser
to see what RDF is being returned [although of course there are ways around
that] - which makes exploration of the interface harder, which is how most
people learn).

Story:
As a user configuring an integration
When asked for a URL to another OSLC implementation, I want to provide
the URL to the web UI of the other implementation (as that is the URL I
know)
In order to set up the integration without having
to search the docs for what URL to use.
(Extension: "I want to provide the URL for whatever
entrypoint/homepage/dashboard I use most in the other tool")

We could achieve this by defining a Link header that
points to the root container for that server, which OSLC servers should
provide on: the home page, and any other page that could reasonably be
used as an entry point. Or on every page, if they really want to be helpful.

But what about getting the URL to a particular "leaf"
container (e.g. project area):

Story:
As a user configuring an integration
When asked for a URL to a specific project within
another OSLC server (e.g. in a configuration file, such as for a headless
operation such as an ant script)
Then I want to be able to provide the URL to the web
UI for that project
In order to set up the integration without having
to search the docs (or the UI) for what URL to use.

We could achieve this by having a separate link header
that points to the container for 'the current scope'. "Project"
pages (or "tenant" pages, or whatever your level of modularity/scope
is) would then include both a link to the root container and a link to
their own container.
When a URL is given to an interactive process, it
could perform make an HTTP HEAD request on it. If it only has a root container
link, it uses that. If it has both a root container link and a 'current
scope' container, it asks the user which one to use. if it has neither,
it performs a GET to see if the body contains a container (although that
should have been visible from the HEAD too) or to see if it is a V2 catalog,
service provider or service (if v2 compatible).




[1] https://jazz.net/wiki/bin/view/Main/RootServicesSpec#Root_Services_Documents


<oslc-core@lists.oasis-open.org> wrote on 02/12/2014
21:40:39:

> From: Steve K Speicher <sspeiche@us.ibm.com>
> To: "OASIS OSLC Core TC Discussion List"
<oslc-core@lists.oasis-open.org>
> Date: 02/12/2014 21:40
> Subject: Re: [oslc-core] OSLC & LDP: Query
Capabilities, Creation 
> Factories & location of Dialogs
> Sent by: <oslc-core@lists.oasis-open.org>
> 
> I took the liberty to sketch in more detail what I meant from some
> of my comments below.  I've put in a webpage how we can build
upon 
> the LDP Container concept many of the things we depended on in 2.0.
> Requires some new vocabulary as sketched but pretty simple and 
> minimal, perhaps even cleanly layers on queryCapability/creationFactory.
> 
> https://wiki.oasis-open.org/oslc-core/Discovery
> 
> Feedback welcome, we can review at upcoming meeting. 
> 
> Thanks,
> Steve Speicher
> IBM Rational Software
> OSLC - Lifecycle integration inspired by the web -> http://open-services.net
> 
> 
> 
> From:        Steve K Speicher/Raleigh/IBM@IBMUS
> To:        "OASIS OSLC Core TC Discussion
List" <oslc-
> core@lists.oasis-open.org> 
> Date:        12/02/2014 08:58 AM 
> Subject:        Re: [oslc-core] OSLC & LDP:
Query Capabilities, 
> Creation Factories & location of Dialogs 
> Sent by:        <oslc-core@lists.oasis-open.org>
> 
> 
> 
> Hi Martin, 
> 
> Thanks for sharing.  This is timely, as I getting ready to outline
> this in more detail.  I have done some work internally and on
my 
> todo list for this month to publish it out.  I'll comment directly
> on some of the points you've raised below. 
> 
> - Steve 
> 
> 
> > From: Martin P Pain <martinpain@uk.ibm.com> 
> > To: "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
> > Date: 12/02/2014 04:55 AM 
> > Subject: [oslc-core] OSLC & LDP: Query Capabilities, Creation
Factories & 
> > location of Dialogs 
> > Sent by: <oslc-core@lists.oasis-open.org> 
> > 
> > As we move OSLC 3 to be based on LDP, I presume Query Capabilities
and 
> > Creation Factories will be replaced by capabilities from LDP.
> > 
> > As I'm starting to draft the Automation v3 spec, I've come to
the place 
> > where I need to be able to refer to the definition of the headless
query/
> > selection and creation capabilities. 
> 
> I believe we don't need to define much of this in domain specs, you
> just need to leverage some basic ways that LDP and Core expose 
> capabilities and clients can discover it. 
> 
> > This also raises the question: are we keeping the existing 
> > oslc:ServiceProvider and oslc:Service resources? I see no reason
not to. 
> From a pure 3.0 spec perspective, no.  I see no reason to require
these. 
> From a compatibility with 2.0 specs, then yes of course we'd need
to. 
> 
> > 
> > So my expectation of how this would go is: 
> > 
> > 1. An oslc:ServiceProvider: 
> > 
> >         a) which is possibly discoverable
from an 
> oslc:ServiceProviderCatalog 
> >         b) would contain one or more oslc:Service
resources 
> We could just have LDP Containers.  Perhaps you could outline
the 
> specific needs of what a oslc:ServiceProvider should have, so a 
> client/server could satisfy a certain.  Typically the needs are
that
> a client needs to interaction with a set of services that operate
on
> types of resources, such a container. 
> 
> > 2. These oslc:Service resources: 
> > 
> >         a) would each identify which OSLC
domain they operate in 
> using their 
> >         oslc:usage property 
> > 
> >                 i) (I
believe this can also exist at the 
> oslc:ServiceProvider level) 
> > 
> >         b) Link to LDP containers for each
of the resource types 
> they work with 
> > 
> >                 i) (They
may have more than one container for eachresource 
> > type, e.g. 
> >                 Automation
Requests ready for execution, and 
> Automation Request 
> >                 templates)
> 
> Essentially, you can think of what a "oslc:Service" (and
everything 
> it contains) as an LDP:Container, annotated to provide the needs we
> had before (query, dialogs, types, shapes, usage) 
> 
> >         c) Maybe, they would still contain
the links to the 
> Creation & Selection 
> >         dialogs (i.e. in the same place as
v2) 
> Yes 
> 
> Something like: 
> 
> <> a ldp:DirectContainer; 
>   oslc:creationDialog <#newDialog> ; 
>   oslc:resourceType auto:AutomationRequest. 
> 
> <#newDialog> a oslc:Dialog; 
>   oslc:dialog <http://example.org/ui/newDialog>;
>   dcterms:title "New Automation Request". 
> 
> >         d) (for providers wanting to be compatible
with v2:) would
> contain v2 
> >         Creation Factories and Query Capabilities
> 
> Correct, we should keep the 3.0 specs "pure" and have a
separate 
> "note" on v2 compatibility.  Imagine what the 3.0 spec
would look 
> like to someone who knows nothing about v2 or 2 years from now, 
> should they know anything about v2? 
> 
> There has been some things started and actively being worked now:
> 
> Core 3.0: http://tools.oasis-open.org/version-control/browse/wsvn/
> oslc-core/specs/compat.html 
> ChangeMgmt 3.0: http://tools.oasis-open.org/version-control/browse/
> wsvn/oslc-ccm/trunk/supporting-docs/change-mgt-compatibility.html
> 
> > 3. Those LDP containers: 
> > 
> >         a) would provide LDP's querying mechanism.
(Is there such 
> a thing? I 
> >         can't find it.) replacing v2's Query
Capabilities 
> 
> No, it is being discussed for LDP "2.0".  We could
simply do 
> something like this to advertise v2 query support on LDP Containers
> 
> <> a ldp:DirectContainer ; 
>  oslc:queryType <http://open-services.net/ns/core#OSLCQuerySyntax>.
> 
> or something 
> 
> 
> >         b) where appropriate, would provide
the creation 
> capability (replacing 
> >         v2's Creation Factories) 
> 
> We could call a LDP Container a creation factory, that is all it is.
> Though I'm not sure if we need to carry that v2 terminology forward
in 3.0. 
> 
> >         c) Maybe, it might be appropriate
to link from the container to the 
> >         creation & selection dialogs
for the resources in that 
> container. So 
> >         (for dialogs that are specific to
a single LDP container -
> not all will 
> >         be) all the operations for that container
are linked from 
> the container 
> >         itself. However, compatibility with
v2 would require that 
> the dialogs 
> >         are linked from the oslc:Service.
> 
> Not sure I'm hearing anything I disagree with but not sure I fully
> get the point. I think it would be helpful if we worked an example,
> side-by-side. 
> The way to think of it, starting with a Container...build up from
> there like I mentioned before: dialogs, query, etc. 
> 
> > In particular, right now I need to know: 
> > - Is 3a correct, or will we be keeping Query Capabilities?  
> 
> For at least 1st half of 2015, I think Query Capability will remain
> a thing only on open-services.net.  It is there, we can use it
as 
> needed.  We'll need to decide what we want to do with this longer
term. 
> 
> > I think 3c is also an important point to decide on. 
> > 
> > Thanks, 
> > Martin
> > Unless stated otherwise above:
> > IBM United Kingdom Limited - Registered in England and Wales
with 
> number 741598. 
> > Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
PO6 3AU 
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU