[Oslc-Automation] Definition of "parameter"

[Max Vohlken]

oslc-automation-bounces at open-services.net wrote on 01/18/2012 01:51:31 PM:

> From: Michael F Fiedler/Durham/IBM at IBMUS
> To: oslc-automation at open-services.net
> Date: 01/18/2012 02:01 PM
> Subject: Re: [Oslc-Automation] Definition of "parameter"
> Sent by: oslc-automation-bounces at open-services.net
>
> We'll make this the first main topic for tomorrow's meeting.
>
> What you've layed out in the RDF description of the parameter definition
> and instance examples makes sense from a practical point of view.  I'd
like
> to hear opinions of others on the "required" attribute as Charles has
> described it.  I'm not familiar with other specs using resource attribute
> values this way, but it seems to make sense here.   Resources like
> ChangeRequest or TestPlan have attributes which must be present in the
> resource, but this proposal takes it to the next level of indirection by
> stating the resource must have an instance of this attribute with a
> specific value present.   Logically, it matches what you see in UIs when
a
> parameter is required to do something.  E.g. You cannot run a certain
> automated test without providing parameter values for some test input
data.
>
>
> My comments on the thoughts/questions in the original mail:
>
> 1) I did not specify any type for the Parameter Definition default value
or
> the Parameter Instance value.  Pragmatically, I think the only viable
> choice is String.  I'm not sure if we should spec that or leave it up to
> the discretion of implementers.
>
> MF>  I think we still need to allow for arbitrary value types.  Spec-ing
it
> as string doesn't feel right.  Perhaps we recommend the parameter
subjects
> have a type predicate to give consumers a hint as to what is expected.

Based on the automation I have dealt with in the past, parameter values are
always strings. If parameter values are not strings then what other types
do you think are possible? Can you think of some examples? The only example
I can think of would be some sort of object that has a complex definition.

>
> 2) I did not attempt to support the ordering of parameters.  I don't
> believe there are any likely target systems where that would be required,
> but thought I'd mention it in case anyone else knew of a case where it
> might be necessary.
>
> MF> There's no ordering in RDF unless containers are used.  The OSLC
> guidance has been to not use containers since they are not query
friendly.
> My opinion is we say nothing about ordering unless we hear a strong
> requirement.

Based on how BuildForge deals with its parameters the order of the
parameters is very important. BuildForge supports the ability to substitute
the value of a previously defined parameter into the value of a parameter
that is defined later. So when the BuildForge engine assembles the
execution environment of a step it evaluates the parameters in the order
that they are defined to generate the actual environment that will be used
during the execution. It is even possible to refer to the existing value of
the current variable when generating the new value for the variable. So
this means that it is possible to reference the same variable more that one
time in the list of parameter settings.

For example:

BASELINE=2012.01.16
QUALIFIER=v8.0.0_$BASELINE
BUILDNUMBER=10
QUALIFIER=${QUALIFIER}_$BUILDNUMBER

Notice it is totally fine to have multiple assignments of the QUALIFIER
parameter. It is also fine to refer to the current value during the
assignment.

BuildForge also provide the ability to specify a list of values that a
parameter can be set to. The user is then presented with a drop down list
of these value and they are expected to select one of them. In this case a
default can still be supplied which will preselect the default value in the
list.

Another feature that BuildForge supplies is additional operations besides
normal assignment. From the BF documentation:

Variable Actions


When the system applies a variable to set up the environment for a server,
project, or step, it can do more than simply assign a value to it. You can
choose an Action for each environment variable. The following actions are
available:
      Set: The default option. Assign As causes the system to assign the
      value you specify to the variable, creating the variable if it does
      not already exist.
      Set if not set: This action assigns the value to the variable only if
      the variable does not already exist on the server when the system
      tries to set it. See How the System Applies Environments to Steps for
      more information.
      Append: The system appends the value specified to any existing value
      for the variable.
      Prepend: The system prepends the value to the current value.
      Clear: The system clears the variable, setting it to null. The
      contents of the Value field are not used.
      Delete / Unset: The system deletes the variable on the server. The
      contents of the Value field are not used.
      Assign Hidden: The system assigns the variable, but hides the value
      in the logs, showing it as "*****". Use this option when you are
      including a password or other sensitive information in a variable;
      for example, if you need to include password information in an _MAP
      variable but do not want to make the password visible to users who
      run the project.
      Note: The system normally changes the syntax of a variable in a
      command line to the appropriate form for your operating system (%VAR%
      for Windows®, $VAR for Linux®/UNIX® systems). It cannot do this for a
      hidden variable.

In BuildForge they also have the idea of behaviors that are associated with
each parameter. From the docs.

Special Behavior on Projects


When you create an environment variable, you can define some special
behavior that takes effect when the variable is assigned to a project. Use
this behavior to make your environment variable groups more flexible,
creating groups with some variables which are ignored, read-only, required,
or hidden when the group is assigned to a project.


The On Project property offers the following options:
      Normal: The variable behaves normally when assigned to a project.
      Required: The system prompts for a value for the variable if no
      default value is defined.
      Read-Only: The value of the variable cannot be changed when the group
      is assigned to a project.
      Suppress Display: The variable is not displayed on the project Start
      page, although the value still exists and can be used in steps.
      Must Change: You must change the variable's value when you launch the
      project; if you do not, the system prompts you to change it.


> 3) Given the distinction above between a Parameter Definition and a
> Parameter Instance, should we name the properties in Automation Plan
> differently than in Automation Request and Automation Result or keep it
> "parameters" and let the context be sufficient?
>
> MF> I think we name them distinctly (parameterDefinition,
parameterInstance
> maybe).   Do we still need to distinguish input/output under this model?
I
> am thinking of a case where an Automation Request is created with
> parameterInstance foo=abc, but when the automation actually ran, the
value
> had to be modified to foo=xyz and we want to capture both in the
Automation
> Result.   Is this a real scenario?  or is it sufficient to just allow
> additional paramterInstances to be added to the result as the automation
> runs.
>

When picking the names of the information in a result I'd like us to
remember that the use of the result record is to retrieve information about
what was done by the automation. So one question I would want to answer is
what were the values of the initial parameters when the job was started. So
I'd call these the initial parameters or startup parameters. Another
question I'd ask is what is the state of the runtime environment at this
point in time. So in this case I would be interested in getting the list of
runtime parameters. If the run is complete then conceptually the runtime
environment becomes the final environment. So if I was writing the
orchestrator that we have talked about in previous meetings then I'd query
the result to see if the first job was done and if it was then I'd get the
runtime environment from the first job and then translate it into the
startup environment for the second job. So from previous discussions the
runtime parameters of the job could also have been called the output
parameters.

One thing I realized in the above discussion is that if I want the startup
environment of the job then what I'm really interested in is the
information that was passed in the request object. So it seems to me that
the result should hold a reference to the request object that then can be
used to get the startup environment of the job. If using references to the
actual request object doesn't make sense then I'd like to see the service
provider make a copy of the request object into the result so that from the
point of view of the client they can use the definition of the request
object to retrieve the startup environment of the job.

-Max

> Regards,
> Mike
>
> Michael Fiedler
> IBM Rational Software
> fiedler at us.ibm.com
> 919-254-4170
>
>
>

>              Charles

>              Rankin/Austin/IBM

>              @IBMUS
To
>              Sent by:                  oslc-automation at open-services.net,

>              oslc-automation-b
cc
>              ounces at open-servi

>              ces.net
Subject
>                                        [Oslc-Automation] Definition of

>                                        "parameter"

>              01/16/2012 06:34

>              PM

>

>

>

>

>
>
>
>
> At the last workgroup meeting there was some discussion about whether we
> should define what is on the other end of a "parameter" property or leave
> it up to implementations.  I'd like to revisit that discussion.  I'm of
the
> opinion that we should provide a minimally useful definition that
> implementers could extend if necessary.  One of the key scenarios that we
> want to enable with this first version of the specification is the
> "execution" scenario [1].  I'm concerned about the viability of this
> scenario without having a minimally useful definition of parameters.  To
> that end, I'd like to take a stab at an initial representation for others
> to throw darts at.  My RDF-Fu is weak, so please be kind.  :)
>
> There are at least two different parameters in question.  One is on an
> Automation Plan and provides the name and constraints on possible input
> values.  The other is associated with Automation Requests and Automation
> Results and represents the mapping of a specific value to a specific
named
> parameter.  For lack of better names, I'm going to call the former a
> Parameter Definition and the latter a Parameter Instance.  Let's start
with
> the Parameter Definition.  To provide a minimally useful Parameter
> Definition I think we need at least two pieces of information (possibly
> represented as three pieces of data).  The first is simply the name of
the
> parameter.  The other is an indication of whether the parameter must be
> specified in order for the automation to be successfully executed.  One
> mechanism for this is to indicate a "default value" to be used if none is
> provided.  The presence of this also provides some potentially useful
> information to those looking at an Automation Result, as they can see if
> the value provided was different than the default.  It isn't clear to me
> that the absence of this data necessarily means that the parameter is
> required.  To that end, another option is to have a "required" property
> that indicates whether the parameter must be specified.  Without further
> ado. let's take a stab at how this might look ( in Turtle).
>
> @prefix        ap:
<http://somewhere.com/oslc-automation-provider> .
>
>
> ap:plan1        oslc_auto:parameter        _:parm1 .
> ap:plan1        oslc_auto:parameter        _:parm2 .
> ap:plan1        oslc_auto:parameter        _:parm3 .
>
> _:parm1        foaf:name                "must_have" .
> _:parm1        oslc_auto:required        oslc_auto:required_yes .
>
> _:parm2        foaf:name                "might_have" .
> _:parm2        oslc:defaultValue        "some value" .
> _:parm2        oslc_auto:required        oslc_auto:required_no .
>
> _:parm3        foaf:name                "may_have" .
> _:parm3        oslc_auto:required        oslc_auto:required_no .
>
> The first definition indicates there is a required parameter with a name
of
> "must_have". The second definition indicates there is an optional
parameter
> with a name of "might_have", which if no value is specified a default
value
> of "some value" will be used.  The third definition indicates there is an
> optional parameter with a name of "may_have", which if no value is
> specified, no default value will be provided.
>
> The information needed to define a Parameter Instance is a little less
than
> for a Parameter Definition.  All that is required is the name of the
> parameter and the value of the parameter.  While these could be specified
> as direct "name=value" strings, I think it is better to separate the name
> from the value.  So, an Automation Request specifying information for the
> plan above, might have parameters as such.
>
> @prefix        ap:
<http://somewhere.com/oslc-automation-provider> .
>
>
> ap:req1                oslc_auto:parameter        _:parm1 .
> ap:req1                oslc_auto:parameter        _:parm2 .
>
> _:parm1        foaf:name                "must_have" .
> _:parm1        rdf:value                "here you go" .
>
> _:parm2        foaf:name                "may_have" .
> _:parm2        rdf:value                "more information" .
>
> This indicates that there are two parameters specified one with a name of
> "must_have" and corresponding value of "here you go", and another with a
> name of "may have" and a corresponding value of "more information".
>
> A few more thoughts/questions before I finish.
>
> 1) I did not specify any type for the Parameter Definition default value
or
> the Parameter Instance value.  Pragmatically, I think the only viable
> choice is String.  I'm not sure if we should spec that or leave it up to
> the discretion of implementers.
>
> 2) I did not attempt to support the ordering of parameters.  I don't
> believe there are any likely target systems where that would be required,
> but thought I'd mention it in case anyone else knew of a case where it
> might be necessary.
>
> 3) Given the distinction above between a Parameter Definition and a
> Parameter Instance, should we name the properties in Automation Plan
> differently than in Automation Request and Automation Result or keep it
> "parameters" and let the context be sufficient?
>
> That's enough for now.  Have at it.  :)
>
> [1] http://open-services.net/bin/view/Main/AutomationExecutionScenario
>
> Charles Rankin
> Rational CTO Team -- Mobile Development Strategy
> 101/4L-002 T/L 966-2386_______________________________________________
> Oslc-Automation mailing list
> Oslc-Automation at open-services.net
>
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
>
>
>
> _______________________________________________
> Oslc-Automation mailing list
> Oslc-Automation at open-services.net
>
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
>