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

[Steve K Speicher <sspeiche@us.ibm.com>]

Responses woven in...

> From: Martin P Pain <martinpain@uk.ibm.com>
> To: Steve K Speicher/Raleigh/IBM@IBMUS
> Cc: "OASIS OSLC Core TC Discussion List"
<oslc-core@lists.oasis-open.org>
> Date: 12/04/2014 05:27 AM
> Subject: Initial discovery (was: [oslc-core]
OSLC & LDP: Query Capabilities,
> Creation Factories & location of Dialogs)
> 
> 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. 
> 
In v2, it could be thought that the ServiceProvider
(or ServiceProviderCatalog to find the SP) is that one 1 URL.
I think of Jazz Root Services is provide additional
triples into ServiceProviderCatalog (which is just a container for SPs).
 There is an open work item that is for making it fully a compliant
SPC, it is so close.

> 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. 
> 
Right, this is basically what v2 has.

> 
> 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 

This is not true, SPCs can include SPCs that can include
SPCs that can...there is no limit.

> 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. 
>
I think this is where we might eventually get to.
 For example, a "Project" or "Program" or "Product"
provides a set of containers.  We don't need a notion of SPC to achieve
this.  A produce can expose a URL to use for configuration, then the
client must look for certain headers or triples.  Much like 2.0.
 
> 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. 
> 
I would say that clients are look for Containers of
a certain type.  I agree, there are cases (if a server implementation
provided infinite depth and didn't provide the Container that client was
looking for) where the could never complete.

I would expect clients to have some depth or time
limit and look for a Container that met its criteria: type of resource,
dialogs supported, etc.  If we find we need to define a type for one
of those kinds of containers (like Service or SP) or just a standard predicate
oslc:end-point (or whatever)

One thing we talked about (a long time ago) was to
provide a "delegated end-point dialog", basically a selection
dialog to help configure or get "that one URL".  We could
explore this more if members would find this valuable.

> 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).
> 
OSLC Resource Containers?

Though, could it not be possible to have a container
whose members are both leafs and containers?  Mind blown?  BTW,
this was possible in v2 as well.

> 
> 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).
> 
These users willing to add response headers or support
the OPTIONS verb on that URL?  Just some other alternatives to sending
back RDF on a GET.

> 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. 
> 
We'd have to define what a root container is but yes,
we could have a URL for a place to find configuration/setup information
or other methods.

We used "oslc:details" predicate in v2 to
define such a web ui URL from oslc:ServiceProvider

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

See "oslc:details" from SP from before or
conneg.

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

I guess I'm not following what the problem is here
with v2.

- Steve

> 
> 
> 
> [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