[Oslc-Automation] Keeping low barriers of entry - defining implementation archetypes?

[Martin P Pain]

My concerns over using autoPlans for teardown (or any other arbitrary 
actions) are mainly in the area of not wanting to impose too much of a 
burden on the simpler of implementations, while also wanting the scenario 
to work as much as possible when those simple implementations are in use. 
So I want to write up my thoughts on this first. I also touched on this at 
the end of my email on Execution environment scenario for deploy subdomain
.

Apologies in advance for the long email.
Contents:
# Overview
# Suggested categories
# Topologies
# What to do with this
# Profiles & modules


Overview:
---------

My suggestion is that in the spec we define types/categories that we 
expect (or observe) implementations to fall into. We could also define 
some of the most common "topologies" between these categories. That way we 
can consider which of these topologies each scenario would be useful in, 
and try to make them work in all the applicable topologies, making sure 
that we don't raise the barrier of entry for supporting these scenarios 
too high for basic implementation (if possible).

For example, if we consider that the topology of a "thin/basic delegated 
UI consumer" talking to a "full-featured/advanced/smart provider" is 
appropriate for a given scenario (e.g. teardown) then we ought to make 
sure there is no (or minimal) burden of understanding specifics of the 
scenario in the client.


Suggested categories:
---------------------

The categories that exist in my mind are as follows (note than any 
specific implementation may fall into one or more of these categories, or 
occasionally none):
"Basic consumer":
    Intention: To provide a UI onto existing providers (or
              to be an adapter to another protocol/API).
    Characteristics: Does not "own" any resources of its own, merely
             operates on other providers' resources. Limited or no
             storage of data other than caches of providers' data.
             Limited or no business logic beyond OSLC-defined logic.
    Subcategories: "Basic delegated UI consumer" - only implements
             delegated UI interactions, plus some minimal RDF queries.
             "Basic RDF consumer" - only implements RDF-based
             interactions.
    Example: Mobile app (because you want anything you create from a
             mobile app consumer to be available to other consumers of the
             provider, e.g. through a web UI). Basic delegate UI consumer.
    Example: Adapter to expose OSLC automation resources from any provider
             to a specific consumer product via its custom APIs. Basic RDF
             consumer.

"Basic provider":
    Intention: To provide an OSLC automation interface to some process
             (or to be an adapter from another protocol/API).
             Not to provide advanced "management" of automation.
    Characteristics: Exposes automation plans from its underlying system.
             Executes requests. May support creation of plans, but
             only if you know its provider-specific vocabulary.
             Does not support advanced features (present or
             future) such as scheduling, approvals, etc. I expect these
             implementations would provide both delegated UI and RDF
             -based interactions, but we could subcategorise thse in the
             same way as the basic consumers.
    Example: Adapter to expose a product's custom APIs to OSLC automation
             clients, such as the plugins that are available for software
             that is not natively an OSLC provider.

"Smart consumer":
    Intention: To provide "management" of automation provided by basic
             providers.
    Characteristics: In addition to operating on providers' resources, may
             also own resources of its own, e.g. pre-created
             "templates". May store other data, such as schedules
             for execution and governance rules.
    Example: See "smart consumer/producer" examples below.

"Smart provider":
    Intention: To provide "management" of automation it provides.
    Characteristics: In addition to providing everything from the "basic
             provider" profile, also supports some advanced features
             such as scheduling, governance, etc. It may
             support creation of new resources, such as plans that
             are specialisations of other plans with input parameters
             specified, or plans that are composed of other plans
             (e.g. test suites).
    Example: Any provider wishing to provide an entire solution that can 
             be used by basic consumers.

"Smart consumer/producer":
    Intention: To provide "management" of other providers' automation and
             expose this over an OSLC interface. Or, a smart provider that
             consumes other providers in order to support its own
             automation.
             This may simply be the combination of the smart consumer and
             smart provider categories, but is likely to be in 
             interesting topologies, so I have brought it out separately.
    Characteristics: Consumes other providers. May either re-expose those
             resources, or expose its own resources which can/may/require
             to use the automation plans on the providers it consumes.
             May provide advanced features. May act as a 'middle man'
             between basic consumers and basic providers, making the
             advanced features available in those interactions. May
             provide a single point of control in situations where there
             are basic (or smart) consumers and providers in use.
    Example: Any orchestrator is likely to be in this category, as it
             consumes other providers to orchestrate, and may
             expose the entire combined lifecycle as an autoPlan.
    Example: RQM, which consumes other providers (e.g. build) to add value
             to its own automation plans (tests, etc).

Obviously the advanced features in the "smart" categories will differ from 
implementation to implementation. Some advanced features will be 
OSLC-defined, many will not.


Topologies:
-----------

"Basic consumer" (either type) with "Basic provider" - the simplest
  topology, but by far least powerful.

"Basic consumer" with "Smart provider" - all advanced features are
  the responsibility of the provider, most likely only available to the
  consumer through the delegated UIs (to avoid it needing to know about
  the RDF vocabularies of the advanced features), but self-descriptive
  parts of the spec (e.g. resource shapes and input parameters) also
  help "Basic RDF consumers" use the advanced features without knowing
  about them in advance.

"Smart consumer" with "Basic provider" - all advanced features are
  the responsibility of the consumer, which gives the user more powerful
  UI, but some advanced features may not make sense this way round.
  If multiple consumers are used with a simple basic provider then there
  is likely to be a lack of sharing of resources between those clients.

"Smart consumer" with "Smart provider" - this is likely to be confusing to
  the user, as features may be duplicated between the consumer and
  provider, and those duplicates may not work well together. e.g. if both
  support scheduling then there will not be a single place to view all
  the scheduled requests - users would have to be organised to use the
  feature on only one side, or remember to check both.
  For this reason (in addition to giving lower barriers of entry) I
  suggest that we encourage most implementations that are solely a
  consumer or a producer (i.e. not a "smart consumer/producer") to be
  "basic", and encourage them to be used with a "Smart consumer/producer"
  in the middle to provide the single point of coordination and advanced
  features. I don't know how feasible this is.

One or more "Basic consumers" consuming a "Smart consumer/producer"
consuming one or more "Basic providers"
  - this is by far the most flexible topology. If the smart
  consumer/producer reexposes the plans it consumes, then this topology
  can have many consumers, each of which only need to be configured with
  a single provider; and many providers, each of which only need to be
  configured on a single consumer.
  In any case I believe this is a good topology for consideration, as I
  expect it will bring to light most of the issues that exist with a
  scenario.


What to do with this:
---------------------

If this sounds like a good way to think about things, then I suggest that 
we create a wiki page for these categories and topologies alongside the 
scenarios page (and have a new one for each version of the spec, as we do 
with the scenarios pages).


Profiles & modules:
-------------------

This could also inform the creation of "profiles" or "modules" that we 
have talked about briefly before. I see "profiles" to be the subsets of 
the sepc that are needed for each OSLC-defined advanced scenario (e.g. 
templates, or teardown) - plus one for each of the "basic" categories 
(which are likely to consist merely of all the applicable "MUST" 
statements).

In my mind these "profiles" would be made up of the "modules" that the 
spec could be broken down into. e.g. "automation result query capability" 
is a "module", which is likely to exist in many (but not all) "profiles".

The "modules", as I use the term here, are any 'functionally substantial' 
sections of the spec qualified by an "if" condition or a "SHOULD" or "MAY" 
statement. (e.g. the sentence "If the service provider supports 
cancelation of automation executions" suggests that "cancelation of 
automation executions" is a module by this definition). (That definition 
gives the "optional modules" - any other 'functionally substantial' 
sections under "MUST" statements would be the required modules, which 
would be part of all profiles).

This - if made to stand out on the spec - could guide new implementors on 
the areas that they need to implement. This could be either the minimal 
they need for a consumer or provider, or what they need to include for a 
particular scenario. (e.g. it's all very well including the "template" 
creation dialogs in the spec, but if in practice it's useless without a 
particular other module, specifically the auto request creation factory, 
then we ought to make that clear). This should aid both readability of the 
spec, and lower the barriers to entry for "basic" implementations.

It's possible that this sort of thing was completely unnecessary in the 
previous version of the spec, but it might prove very useful as we support 
more optional scenarios.

These profiles could then inform the test suites in Eclipse Lyo, so 
implementors can easily select "I want the test suites for these 
particular profiles", rather than having the suites fail and them have to 
work out if they've understood the spec correctly or just are not 
implementing an optional part.




There's lots of information there. Hopefully at least a couple of you have 
had the time to get through it all...
If there is consensus that something like this is good - even if you don't 
agree with the particular categories/topologies that I have suggested - 
then I will transfer this information to the wiki to be a work in progress 
there.

I haven't looked at other domains to see if any of them do something 
similar - let me know if you're aware of anything.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20130517/40d5489e/attachment-0003.html>