Post by dmitry on Aug 28, 2023 10:39:56 GMT
Hello everyone,
I would like to propose a feature of extended action parameters to be incorporated into the Redfish specification.
For the use case introducing the problem to solve please consider the following example:
There is schema for four resource types:
ProgramTemplate resource
This resource represents a program (executable) which can be launched on the system.
The schema provides "Execute" action to launch the program.
The program resource may be thought of as a job or task template which can be instantiated many times with varying parameters.
The set of launch parameters depends on a program purpose which is specific for each resource instance: it may take no parameters at all, may take some optional parameters to alter the default behavior, or mandate some input parameters.
It is expected that different vendors would create underlying programs, then at the system integration phase they would be installed on a system and then be utilized during normal system operation.
It is also expected that some systems would also add or remove program templates during normal system operation.
ProgramTemplateCollection
Resource collection for ProgramTemplate resource instances
ExecutedProgram resource
This resource represents an instantiated ProgramTemplate which depending on the parameters provided be in either running or scheduled (or other) state.
This can be thought of as a job or task which is running or pending its execution.
The resource tracks down the execution state and execution metrics, and provides information of the exact launch parameters which were used to instantiate the program.
ExecutedProgramCollection
Resource collection for ExecutedProgram resource instances
From the above description of the ProgramTemplate schema comes a necessity to provide a placeholder for any amount of extended parameters which may be required for launching a specific program instance, The underlying resource schema can't envision or assume all the possible argument sets.
Considered ways to mitigate the problem:
1. Create enough slots for parameters.
For this approach the schema for the "Execute" action would be provided with a certain amount of nullable (optional) parameters, so this would be enough for 99% of possible use cases.
The main caveats with such approach are:
a. nothing would hint whether a parameter X is optional or mandatory
b. nothing would hint of the parameter X actual purpose and expected format for a specific ProgramTemplate instance.
c. what amount of parameters would sufficiently cover 99% of use cases
2. Create a collection parameter where each entry expects Name/Value pair.
For this approach the schema for the "Execute" action would be provided with one collection(PrimitiveParameter) parameter serving as an extension point where the PrimitiveParameter complex type would consist from a single field of some primitive type (much the same as Bios.v1_0_0.Attributes or EventDestination.v1_0_0.HttpHeaderProperty).
The caveats with such approach are almost the same except the "c" variant since the collection could take as much of entries as required.
To mitigate the caveats "a" and "b" it is possible to introduce a field in the ProgramTemplate resource schema which would describe the expected extended parameters by the specific instance (similar to the ActionInfo resource). The only problem here is that the description wouldn't be a standard one, thus a generic Redfish client wouldn't take it into account.
3. Provide a separate schema for each ProgramTemplate instance.
For this approach each vendor would provide a schema for their particular program which would define a specific resource schema which is based on the ProgramTemplate schema, and a new "ProgramTemplate.Execute" action bound to the specific resource type.
The OData Specificaton 4.0 allows defining several action with the same name in the same namespace if the bound resource is different.
Though this approach solves all the caveats introduced by approaches 1 and 2, it brings its own:
a. Resource naming problem. Vendors for programs must come with a solution to not create resource with conflicting names.
b. The ExecutedProgram namespace would be sparse where different schemas would define the same "Execute" action for specific bound resource. It's not clear if such sparse namespace approach fits into the overall Redfish schema design paradigm.
c. Specific ProgramTemplate resource schema wouldn't actually extend the ProgramTemplate resource schema since there's no necessity. Moreover, a possible extension may not be welcome.
d. Specific "Execute" action may not provide parameters defined for the base ProgramTemplate resource schema.
So, we propose to extend the Redfish specification to allow the above use case with the following extensions to be introduced:
1. Add "ActionInfo.PrimitiveParameter" complex type which would have identical definition as Bios.v1_0_0.Attributes or EventDestination.v1_0_0.HttpHeaderProperty
2. Add "@redfish.ExtendedParameters" into the RedfishSettings dictionary to annotate a parameter with "collection(ActionInfo.PrimitiveParameter)" type. This parameter would serve as a placeholder for the extended parameters expected by a parent Action. The client may expect that the ActionInfo resource for the action is present and it contains the extended parameter description.
3. Add "ActionInfo.ExtendedParameters" complex type to describe an extended parameter.
4. Extend "ActionInfo.ActionInfo" resource to include the collection of "ActionInfo.ExtendedParameters"
5. Add a clause to the Redfish specificatoin on using the extended parameters and "@redfish.ExtendedParameters" annotation.
6. Extend the "Base" message registry with the "MissingExtendedParameter" message with "Critical" severity where a list of missing but required extended parameters is provided.
The overall use case with the following proposal would look like follows:
1. Generic Redfish client reads the "ProgramTemplate" resource schema and notices the "@redfish.ExtendedParameters" annotation under say "ProgramParameters" parameter of type "collection(ActionInfo.PrimitiveParameter)".
2. The client reads the ActionInfo resource for the action for each specific resource instance to understand what specific extended parameters are expected by the resource in order to be able to correctly create an input dialog for the "Execute" action.
For the legacy clients which wouldn't understand the "@redfish.ExtendedParameters" schemantics, the "MissingExtendedParameter" extended error would be a way to mitigate the problem of launching a program.
Looking forward to comments.
Regards,
Dmitry
I would like to propose a feature of extended action parameters to be incorporated into the Redfish specification.
For the use case introducing the problem to solve please consider the following example:
There is schema for four resource types:
ProgramTemplate resource
This resource represents a program (executable) which can be launched on the system.
The schema provides "Execute" action to launch the program.
The program resource may be thought of as a job or task template which can be instantiated many times with varying parameters.
The set of launch parameters depends on a program purpose which is specific for each resource instance: it may take no parameters at all, may take some optional parameters to alter the default behavior, or mandate some input parameters.
It is expected that different vendors would create underlying programs, then at the system integration phase they would be installed on a system and then be utilized during normal system operation.
It is also expected that some systems would also add or remove program templates during normal system operation.
ProgramTemplateCollection
Resource collection for ProgramTemplate resource instances
ExecutedProgram resource
This resource represents an instantiated ProgramTemplate which depending on the parameters provided be in either running or scheduled (or other) state.
This can be thought of as a job or task which is running or pending its execution.
The resource tracks down the execution state and execution metrics, and provides information of the exact launch parameters which were used to instantiate the program.
ExecutedProgramCollection
Resource collection for ExecutedProgram resource instances
From the above description of the ProgramTemplate schema comes a necessity to provide a placeholder for any amount of extended parameters which may be required for launching a specific program instance, The underlying resource schema can't envision or assume all the possible argument sets.
Considered ways to mitigate the problem:
1. Create enough slots for parameters.
For this approach the schema for the "Execute" action would be provided with a certain amount of nullable (optional) parameters, so this would be enough for 99% of possible use cases.
The main caveats with such approach are:
a. nothing would hint whether a parameter X is optional or mandatory
b. nothing would hint of the parameter X actual purpose and expected format for a specific ProgramTemplate instance.
c. what amount of parameters would sufficiently cover 99% of use cases
2. Create a collection parameter where each entry expects Name/Value pair.
For this approach the schema for the "Execute" action would be provided with one collection(PrimitiveParameter) parameter serving as an extension point where the PrimitiveParameter complex type would consist from a single field of some primitive type (much the same as Bios.v1_0_0.Attributes or EventDestination.v1_0_0.HttpHeaderProperty).
The caveats with such approach are almost the same except the "c" variant since the collection could take as much of entries as required.
To mitigate the caveats "a" and "b" it is possible to introduce a field in the ProgramTemplate resource schema which would describe the expected extended parameters by the specific instance (similar to the ActionInfo resource). The only problem here is that the description wouldn't be a standard one, thus a generic Redfish client wouldn't take it into account.
3. Provide a separate schema for each ProgramTemplate instance.
For this approach each vendor would provide a schema for their particular program which would define a specific resource schema which is based on the ProgramTemplate schema, and a new "ProgramTemplate.Execute" action bound to the specific resource type.
The OData Specificaton 4.0 allows defining several action with the same name in the same namespace if the bound resource is different.
Though this approach solves all the caveats introduced by approaches 1 and 2, it brings its own:
a. Resource naming problem. Vendors for programs must come with a solution to not create resource with conflicting names.
b. The ExecutedProgram namespace would be sparse where different schemas would define the same "Execute" action for specific bound resource. It's not clear if such sparse namespace approach fits into the overall Redfish schema design paradigm.
c. Specific ProgramTemplate resource schema wouldn't actually extend the ProgramTemplate resource schema since there's no necessity. Moreover, a possible extension may not be welcome.
d. Specific "Execute" action may not provide parameters defined for the base ProgramTemplate resource schema.
So, we propose to extend the Redfish specification to allow the above use case with the following extensions to be introduced:
1. Add "ActionInfo.PrimitiveParameter" complex type which would have identical definition as Bios.v1_0_0.Attributes or EventDestination.v1_0_0.HttpHeaderProperty
2. Add "@redfish.ExtendedParameters" into the RedfishSettings dictionary to annotate a parameter with "collection(ActionInfo.PrimitiveParameter)" type. This parameter would serve as a placeholder for the extended parameters expected by a parent Action. The client may expect that the ActionInfo resource for the action is present and it contains the extended parameter description.
3. Add "ActionInfo.ExtendedParameters" complex type to describe an extended parameter.
4. Extend "ActionInfo.ActionInfo" resource to include the collection of "ActionInfo.ExtendedParameters"
5. Add a clause to the Redfish specificatoin on using the extended parameters and "@redfish.ExtendedParameters" annotation.
6. Extend the "Base" message registry with the "MissingExtendedParameter" message with "Critical" severity where a list of missing but required extended parameters is provided.
The overall use case with the following proposal would look like follows:
1. Generic Redfish client reads the "ProgramTemplate" resource schema and notices the "@redfish.ExtendedParameters" annotation under say "ProgramParameters" parameter of type "collection(ActionInfo.PrimitiveParameter)".
2. The client reads the ActionInfo resource for the action for each specific resource instance to understand what specific extended parameters are expected by the resource in order to be able to correctly create an input dialog for the "Execute" action.
For the legacy clients which wouldn't understand the "@redfish.ExtendedParameters" schemantics, the "MissingExtendedParameter" extended error would be a way to mitigate the problem of launching a program.
Looking forward to comments.
Regards,
Dmitry