I'm curious, what use case for OSLC spec makes BuildForge current design of dealing with parameters relevant here?
-Barys From: Max Vohlken/Lexington/IBM@IBMUS To: Michael F Fiedler/Durham/IBM@IBMUS Cc: [email protected], [email protected] Date: 01/18/2012 01:24 PM Subject: Re: [Oslc-Automation] Definition of "parameter" Sent by: [email protected] [email protected] wrote on 01/18/2012 01:51:31 PM: > From: Michael F Fiedler/Durham/IBM@IBMUS > To: [email protected] > Date: 01/18/2012 02:01 PM > Subject: Re: [Oslc-Automation] Definition of "parameter" > Sent by: [email protected] > > 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 > [email protected] > 919-254-4170 > > > > Charles > Rankin/Austin/IBM > @IBMUS To > Sent by: [email protected], > oslc-automation-b cc > ounces@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 > [email protected] > http://open-services.net/mailman/listinfo/oslc-automation_open-services.net > > > > _______________________________________________ > Oslc-Automation mailing list > [email protected] > http://open-services.net/mailman/listinfo/oslc-automation_open-services.net > _______________________________________________ Oslc-Automation mailing list [email protected] http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
