[Oslc-Automation] Availability Spec review - my feedback - OSLC Actions
Martin P Pain
martinpain at uk.ibm.com
Thu May 8 10:09:21 EDT 2014
More feedback:
* + You don't have any text about achieving any of those scenarios. In
particular, about how the client can change the condition of an
availablity resource. We don't need to explain how to achieve the
scenarios - that can be left for the scenario pages - but I don't think
there's enough in the spec for a reader to do it themselves.
* + The one thing that is in there is the link to AutomationPlans via the
dcterms:contributor link. However, we don't describe how to know which
plans do what. I propose that, as mentioned in a meeting a while back (I
presume you already had the draft written by that stage), instead of
linking to Plans via that predicate, we use oslc:action and link to
oslc:Action resources. Also that we define rdf:type values (that are
rdfs:subClassOf oslc:Action) for the different actions that are required
by the scenarios, and define in the Availablity spec what each of these
types of actions mean.I could draft such changes if you would like me to,
but it would probably be a good validation of the Actions spec if you
attempt it yourselves.
Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
OASIS Open Services for Lifecycle Collaboration - Automation technical
committee chair
E-mail: martinpain at uk.ibm.com
Find me on: and within IBM on:
IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
From: Martin P Pain/UK/IBM at IBMGB
To: oslc-automation at open-services.net, Juergen Holtz
<HOLTZ at de.ibm.com>, Tim Friessinger <TFRIESS at de.ibm.com>,
Date: 08/05/2014 14:42
Subject: [Oslc-Automation] Availability Spec review - my feedback
Sent by: "Oslc-Automation"
<oslc-automation-bounces at open-services.net>
Here is my feedback on the original OSLC Availablility draft spec pdf (
http://open-services.net/wiki/automation/Availability-Specification/)
Key to my feedback notations:
* - A minor point, indicated by a leading hyphen/minus sign. (In grey in
the original HTML email)
* . A medium-level point, indicated by a leading period/dot.
* + An important point, indicated by a leading plus sign.
* . "In quotes, -deleted- words are in red strikethrough with a hyphen
either side , _inserted_ words are in green underline, with an underscore
either side (in the original HTML email - which I believe you can find in
a link in the archives)."
Here is my feedback. I suggest discussing this via e-mail, as getting as
many point as possible sorted via e-mail should be more efficient than on
the call. Anything contentious or that requires in-depth discussion can be
discussed at the meeting next week. There are lots here, including many
minor ones. Hopefully they're useful. Feel free to question anything
(anyone). There are a couple of questions aimed at John Arwe for
clarification - these are makred with "John" in bold.
Editorial comments:
* - The wiki page doesn't need to be "workgroup only".
Introduction:
* - Would this be better to extend Automation, to make best re-use of
Automation's plans?
* - To be able to describe a system that is (highly) available
Terminology:
* - "Availability condition" - to me, "condition" suggests "requirement"
(e.g. boolean expression, if-statement). However, on Googling it, the
sense of "state, situation" does come out as the primary definition, so I
won't make a fuss. "State"/"Status" would also have its problems (sense of
state-machine versus wider condition). I've just mentioned it to make sure
you've thought about the possible ambiguity when looking at the term
"availability condition" when not next to its definition as it is in this
section.
* - "Recommended as a specialization of an Availability Group." (also for
"...of an Availability Resource")
Compliance:
* . Footnote 4: "3Support for all HTTP methods for all -automation-
_availability_ resources is not required "
Namespaces:
* - I expect John would suggest "oslc-availability" for the standard
prefix, but oslc_avail is more consistent with Automation 2. I don't mind
either way.
* . I would suggest something longer in the namespace URI though, perhaps:
http://open-services.net/ns/availability# I know other specs used very
short forms, but that caused problems with "Configuration management"
versus "change management", and I believe the more recent convention is to
use a longer string in the URI. Consistency here isn't important, as the
URI is repeated less than the prefix.
Availability definitions:
* - "It is recommended that any additional properties exist in their own
unique namespace and not use the namespaces defined in this specification.
" - I expect this was copied from Automation, but this could be a stronger
requirement. It would be bad practice to define properties in the
namespaces defined in this specification without the agreement of the
working group or technical committee responsible for maintaining the
namespace. (A few paragraphs down we make it a SHOULD - I guess that's the
same as "recommended" in prose).
* + The arrow and name of the relationship between Group and Availability
Resource (AR) appear to disagree with each other. Either the group is
pointing to a resource as a "member", or the resource should be pointing
to the group(s) it is a "memberOf". In the resource tables it suggests
that the link is pointing from the AR to the Group.
* . When I first looked at this diagram I wasn't convinced about
Availability Condition (AC) being a separate resource. Having read later
it looks like there can be multiple ACs for an AR, each as a snapshot at a
given timestamp (dcterms:created). Is that the intention? If not, what was
the reasoning behind them being different resources?
* . I'm not sure dcterms:contributor is the best relation to use for the
link to resources that the AR is affected by. dcterms deifne its raneg as
Agent, which is "A resource that acts or has the power to act. ". Is it
your intention to link to resources that can act on on the AR? As opposed
to ones that the AR acts on? (Or can affect the AR's state not by acting
on it, but merely by changing its own state). The definition in the
resource table further down suggests the usage is correct - the target of
the link is actively acting on the AR. This isn't clear in the diagram
whether the contributor is affecting the AR actively, or merely its state
is reflected in the AR.
Resource: AR
* - dcterms:description "Descriptive text (reference: Dublin Core) about
_the_ resource"
* + Availability-specific properties: Please create a vocab document (or a
wiki page to use as a draft) to define each of these terms outside the
conext of these particular resource tables. This helps create vocabularies
with more value and reusability, and also helps discover any ways in which
the terms can be improved even inside the scope of the resource tables.
* + oslc_avail:actualCondition: You have read-only set to true. I expect
this is consistent with some other specs, but it's worth considering that
in some scenarios (although admittedly not within our defined scope) might
have the resources stored in a separate repository from the actor who
determines their contents. In that case, they need to be updatable.
John: What does "read-only" technically mean here? The most important
question here for this version is: would changing the read-only flag for a
property in a subsequent version cause any problems? And is a provider
non-compliant if they allow it to be written? If not, I'm happy to leave
it, as it can always be changed if anyone raises a scenario for those
cases.
* + oslc_avail:memberOf. Is there a particular reason why the link is
pointing in this direction, and not from the group to the members? It
would seem to me that you might more often want to find all members for a
group (part of the scenario "Obtain redundancy information for workloads"
- even if you do have to start at an AR). If we require looking up of
reverse links, we ought to specify exactly how this is expected to be
achieved. I know it's possible with query capabilities, but we ought to
clearly spell out how, to make implementors lives easier. (Whichever
direction the link goes in we might have to do reverse link lookups, but
if the link pointed in the other direction it would only have to be one,
rather than all but one of the group's members. But then again you have to
do the lookup to find out if it's in a group. Perhaps that was your
reasoning, if so you've probably got the link in the correct direction.)
* + oslc_avail:memberOf: Say in the description "It is expect that the
target of this link will be of type Availability Group (or its sub-type
Redundancy Group), but this is not necessarily the case".
Resource: AC
* + compoundState. Mention and link to the predefined values in the
description. Can providers provide their own values? If they can, there
may be a better alternative: The Change Management specs found that for
their states it was useful to add in "state predicates" [1]. These are
single-value properties that indicate some semantics of the resource's
current state.e .g. oslc_cm:closed=[true|false] [2]. So in this case we
could define this as oslc_avail:consistentState=[true|false]. If it is
true, you can read either and get the actual state knowing it is also the
desired state. If it's false you can read whichever one you need knowing
that actual & desired are not consistent. (Is this explicitly mentioned in
a scenario? Whenever someone asks about the reasoning behind something, as
I'm doing here, it would be useful to add a note to any applicable
scenario(s)' wiki pages about that reasoning and how it supports that
scenario. [Although I admit I haven't done this in my work on the Actions
spec.]) See comment below in "Predefined properties" section about
warning/problem distinction. (If we still want that distinction, but also
wanted to use state predicates, we could have a second one for the
"problem" state... maybe).
* + desiredState & currentState. Mention and link to the predefined values
in the description. Say whether provider-specific values are allowed.
* - If provider-specific state values are allowed (which might be a good
idea to support extensibility) then we might want to consider state
predicates for online, offline, stopping and starting. On the one hand
this isn't required by the existing scenarios, but on the other hand it
provides most flexibility going forwards.
* + mttf & mttr: What type of resource? Options probably include: using an
integer, not resource, and specifying units in spec. Or using (hopefully
re-using) some existing time-period resource that can specify its own
units.
Resource: Availability Group
* + dcterms:created -remove "The point in time this condition has
occurred."
* + dcterms:modified: Do we want to make it explicit that new members
added to the group update this? (As they don't add any new triples to this
group resource, so it may not by default.) What about changes to resources
- I guess they don't update this timestamp - do we want to make that
explicit?
* + AEC: Does the HRG AEC have an RDF vocab/representation? If so, can we
link to it? If not, how is this represented?
* . currentlyActive: This predicate name doesn't indicate "count". I'd
prefer something like "currentlyActiveCount" or "numberActive" or (to find
a verb form) "hasActiveMembers" (note the trailing "s" - if it were
linking to a currently active member, it would not have an "s", so this
"S" could [very] subtly suggest that it is a count. But I don't like this
one much, due to that being very subtle.)
* + John: Can range be used like this?
* + SLA: Mention and link to the predefined values in the description. Say
whether provider-specific values are allowed.
Resource: Redundancy Group
* + Should this be an rdfs:subClassOf Availability Group. i.e. why is it
"often" an AG, not always? (Admittedly, I think we can always add
subClassOf in future, but removing it would be harder).
* . "maxActiveTarget", "minActiveTarget". Who is this a target for? Is
this what the provider is trying to achieve, or could this be instructions
to a consumer to start/stop members to meet this target? Could it be
either, or do we want to specify one?
* . "redundancyCapability: Description: Starting with "Information
about..." makes it sound, to me, like it's going to be a resource. Perhaps
"An indication of level of redundancy provided by this group." might be
more fitting for an integer value.
* + synchronizationType: Mention and link to the predefined values in the
description. Say whether provider-specific values are allowed.
Resource: Redundancy Member
* + Again, same question about subClassOf.
* + redundancyRole: Mention and link to the predefined values in the
description. Say whether provider-specific values are allowed.
Sub-domains:
* + No subdomains are explicitly defined.
* + If we only want vendor-specific sub-domains, should we specify an
rdf:Class to use as the rdf:type value of the resource at the target of
the sub-domains identifier URI, so generic consumers can identify which
URIs identify Availability sub-domains? (i.e. This would be used in the
vocab documents that define those sub-domain URIs).
* + In the example, a value is used for "System Automation for z/OS"
sub-domain. (1) This value isn't defined in this spec (at least not that
I've seen so far) so shouldn't use this spec's namespace. An example.com
namespace would be appropriate for an example value. (2) If we want to use
this value in IBM implementations (I presume we do) then it's still in the
wrong namespace. It's a vendor-specific term, so I'd suggest it would be
better in an ibm.com or jazz.net namespace (the latter is Rational-owned,
but has an existing process for publishing public RDF vocab documents, so
might be the path of least resistance). As far as the WG should be
concerned: it's a vendor-specific term, discuss it inside the vendor.
(Well, that's my opinion). We can always provide a list of links to known
vendor-specific terms in an informative section of the spec.
* + "Depending on the sub-domain, an OSLC client can expect predefined
values for the following attributes". Without defining any specific
sub-domains, I'm not sure this communicates much information. Do you mean
"Sub-domains may specify what sub-set of these predicates they use"? Or
maybe "Sub-domains may specify which values they support for each of these
properties"?
Creation Factories/Query Capabilities:
* - "at least one Creation Factor_y_-ies- entry" (perhaps use the
qualified name for the type or predicate)
* - "at least one Query Capabilit_y_-ies- entry" (ditto)
* + "SHOULD support the oslc.properties syntax " SHOULD should be bold.
Delegated UIs:
* + RedundancyMember is missing from table
* . I'd suggest "SHOULD" for AR, AG, RG and RM selection dialogs, as I
expect UI-based clients will really want to use these. Creation dialogs
might not be appropriate for all providers, so MAY seems appropriate for
them.
Predefined properties:
* + These are individuals (values), not properties.The sub-headings are
ok, as they are the properties that the values are for, but the to-level
"Predefined properties" heading seems wrong to me.
* + I know Automation uses a lower-case initial letter for its states, but
I believe the current convention for these sorts of URIs ("individuals")
is to use an initial capital. e.g.
http://open-services.net/ns/availability#Offline.
* . These URIs will point to resources defined in the Availability vocab
document. Should they have a particular rdf:Class for their rdf:type
property, to identify what they are values of/for?
* . Some of these values might be appropriate for contribution to the
Common IT Resource Vocabulary:
http://open-services.net/wiki/reconciliation/Common-IT-Resource-Type-Vocabulary-Version-2.0/
(On the other hand, as all of the properties and values in this spec
relate to resources, and specifically to their availability, perhaps we
should keep them in a separate Availability namespace, but have that
linked from the Common IT Resource Vocabulary, sort of as a
sub-vocabulary.)
* . compountState: Does "warning" mean "currentState does not match
desiredState, but may do at some time in the [near] future" and "problem"
mean "they do not match, and the attempt to move to the desired state
failed and cannot be [automatically] retried"? The description for
"problem" suggests that, but what warning says - "the availablity resource
is still usable" - seems to me to be orthogonal to whether or not it meets
its desired state. It's usable if the currentState is "online", and not
usable if it's any other state, right? I'd suggest letting compoundState
just say whether or not the currentState matches the desiredState
(yes/ok/match, or no/doesn't match. possibly with a "may match soon"/"in
progress" option), and currentState say whether or not the resource is
usable or not. Perhaps this was your intention, in which case I think the
"warning" value needs a better description- and perhaps renaming to
"InProgress" or "Changing".
* . Service Level Properties: Are these properties or values? If values
how do these relate to the predicates of the same name?
* . redundancyRole: If there is only ever one master, would it be better
for this to be a property on the redundancy Group pointing to the master?
HTTP method support:
* + Availability Component = Availablility Resource? Or = {AR, AG, RG,
RM}?
[1]
http://open-services.net/bin/view/Main/CmSpecificationV2?sortcol=table;up=#State_Predicates
[2] Approx 2 pages down from:
http://open-services.net/bin/view/Main/CmSpecificationV2?sortcol=table;up=#Resource_ChangeRequest
Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
OASIS Open Services for Lifecycle Collaboration - Automation technical
committee chair
E-mail: martinpain at uk.ibm.com
Find me on: and within IBM on:
IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. 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
_______________________________________________
Oslc-Automation mailing list
Oslc-Automation at open-services.net
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
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/20140508/bed1977c/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 518 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/bed1977c/attachment.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 1208 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/bed1977c/attachment-0001.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 360 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/bed1977c/attachment.gif>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 518 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/bed1977c/attachment-0002.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 1208 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/bed1977c/attachment-0003.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 360 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/bed1977c/attachment-0001.gif>
More information about the Oslc-Automation
mailing list