Human-readable SDD Content
description
Transcript of Human-readable SDD Content
Human-readable SDD ContentDebra Danielson
CA
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Use Cases to Address
Help available whenever the end user will need to make a decision or a prioritization. Including acceptable values.
- Parameter values
- Alternatives for external dependencies
- Configurations
- Features
- Topologies
Requirements 2.1.2.1.1, 2.1.4.1, 2.6.3.2, 2.10.1
Configurations, Features, Topologies
not in CL1
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Use Cases to Address
Ability for SDD constructor to define anticipated error conditions along with information to understand and remediate
- Dependency check failures
- Change execution failures
- Lifecycle operations
Requirement 2.1.1.4
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Use Cases to Address
Ability for the SDD constructor to define the consequences of a specific action or operation
- Undo
- Unmet requirements
Requirement 2.1.1.6.2, 2.10.1
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Use Cases to Address
Ability for the SDD constructor to define progress and status information
Requirement 2.2.1.11
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Proposal
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Help available whenever the end user will need to make a decision or a
prioritization
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
DisplayElementGroup
Add optional ExtendedInformation- Provides extended information, generally help or assistance in decision making
<Parameter sensitive="false" name="logging.defaultlevel" defaultValue="Level.INFO">
<DisplayName default="Default logging level for logging messages coming from JRE" key="LOGLEVEL_DISP"/>
<Description default="If you are not familiar with this functionality, leave the default value of Level.INFO." key="KEY_LEVEL_DESC"/>
<ExtendedInformation default="
The message is logged at a certain level. The levels are: FATAL, ERROR, WARNING, INFO, DEBUG & TRACE
Selecting a level includes all higher priority levels For example, if the logging level is set to 'WARNING', then all messages of that level or higher are logged, ERROR and FATAL.
For more information, refer to http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html.
key ="KEY_LEVEL_HELP"/>
- Partially addresses 2.6.3.2
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
VariableGroup
Add optional ValueAlternative to Parameter element
- Used in situations to describe alternatives<Parameter sensitive="false" name="logging.defaultlevel" defaultValue="Level.INFO">
<DisplayName default="Default logging level for logging messages coming from JRE" key="LOGLEVEL_DISP"/>…<ValueAlternative value="level.TRACE">
<DisplayName default="Level.TRACE" key="KEY_LEVEL_TRACE"/><Description default="Level.TRACE will cause all messages to be logged."
key="KEY_LEVEL_TRACE_DESC"/><ExtendedInformation default="This could be help on this alternative"
key="KEY_LEVEL_TRACE_HELP"/></ValueAlternative><ValueAlternative value = "Level.INFO"
...</ValueAlternative>
</Parameter>
- Completes 2.6.3.2
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Descriptive Text for Non-CL1 Items
Configurations
Expectation of prioritization of multiple configuration
Use of ExtendedInformation addresses the help requirements
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Descriptive Text for Non-CL1 Items
Features
Already has a structure for enumerating the options, use of ExtendedInformation addresses the help requirements.
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Descriptive Text for Non-CL1 Items
Topologies
No definitions yet for alternative topologies and prioritization thereof
expectation that ExtendedInformation will suffice when those sections are defined
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Extend DisplayElementGroup Use
Extend any references to DisplayElementGroup members to include ExtendedInformation
Review specification to insure that DEG is referenced in all appropriate areas.
- Initial review shows missing in: IdentityType
ArtifactType
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ability for SDD constructor to define anticipated error conditions along with
information to understand and remediate
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
ErrorInformationType
Define anticipated error conditions and describe consequences
Required attributes- type
- value
Optional elements- DisplayElementGroup xsd:string type,
Artifact or context dependent
Should this be a defined set (fatal, error,
warn, info, debug) or artifact / context
dependent?
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
DisplayElementsGroup
Add optional sequence of 1 or more Error:ErrorInformationType elements to DisplayElementsGroup
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Example
<Parameter sensitive="true" name="keystore.password" defaultValue="changeme"><DisplayName default="Password for encrypting the private JRE keystore" key="JDK_PASS_DISP"/><ExtendedInformation default = "Passwords must be at least six characters.
Each password should contain at least two alphabetic characters and at least one numeric or special character. “ key="KEY_PASSWORD"/><Error value = "-1" type="WARN">
<DisplayName default="Invalid password", key="KEY_PWERR_PW"/><Description default="The password you set did not contain at least one
numeric or special character." key="KEY_PWERR_DESC"/></Error><Error value="-2", type="ERROR">
<DisplayName default="Invalid password", key="KEY_PWERR_LEN"/><Description default="The password you set was not long enough. It must
be at least six characters." key="KEY_PWERR_LEN_DESC"/></Error>
</Parameter>
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ability for the SDD constructor to define the consequences of a specific
action or operation
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
ArtifactType
Add DisplayElementGroup to ArtifactType Permits each operation to define the
consequences through Description, ShortDescription and ExtendedInformation
<UninstallArtifact type="q:name" HE_restart_required="no_restart_needed" fileRef="AIXjre.zip"><Description default="description goes here" key="XLAT_KEY"/><ExtendedInformation default="if the install..." key="XLAT_KEY_2"/>
</UninstallArtifact>
Are there any other areas where there are operations?
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ability for the SDD constructor to define progress and status information
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Areas Where Progress is an Issue
Execution of Artifacts Evaluation of Requirements and Constraints
- Topology Requirements and ResourceChecks (runtime has sufficient information to produce appropriate granularity of progress information)
- CustomCheck (runtime may not have sufficient information)
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
The User Would Like to Know:
What is happening in the process as it is executing (this may possibly change during a single artifact execution)
Percent completion
Estimated time to complete
Cancellable, and consequences of cancellation
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
What’s Declarative, and What’s Runtime
If an artifact type has a standard for reporting progress, then the runtime should be able to get this information without including anything in the SDD.
If the artifact type *does not* have a standard, or if the artifact standard doesn’t provide all of the information then the runtime will need information in the SDD to describe
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Issues
Is non-standard progress mechanism definitions in CL1?
Do we need to support both poll and push mechanisms?
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Use Cases
No progress available from artifact during execution at all
Progress available from artifact through API- Some or all information
- Simple or multi-phase
Progress available from artifact through callback- Some or all information
- Simple or multi-phase
Others? Log files?
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Information Needed by Runtime
Does the artifact have a progress mechanism at all?
Does the progress mechanism support %, ETC, and phase/consequence text?
How can the runtime get this information?
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
ProgressInformationType
Define progress information for an artifact
Optional elements- DisplayElementGroup
- Map of variables to the specific items: StepLabel
PercentComplete
TimeToComplete
- One or more CustomChecks, identified as call or callback
This could be any or all of the DisplayElementGroup-like items should we
add an optional attribute of varRef to any DisplayElementGroup?
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
ArtifactType
Add optional element ProgressInfo of type ProgressInformationType to ArtifactType
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Simple Example
No status information available from the artifact<InstallArtifact type="baseInstall" HE_restart_required="no_restart_needed"
fileRef="AIXjre.zip">
<Parameters>
<Parameter value="-c -r -u" name="unzip.options"/>
</Parameters>
<ProgressInfo>
<Description default="Installing AIX Java Runtime Environment, please wait." key="KEY_PROGRESS"/>
<ExtendedInformation default="This installation generally takes 5-10 minutes to complete. etc. etc." key="KEY_PROGRESS_HELP"/>
</ProgressInfo>
</InstallArtifact>
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Complex Example
The installing program has an API to get status information
<ProgressInfo><Description default="Installing AIX Java Runtime Environment, please wait." key="KEY_PROGRESS"/><PercentComplete varRef="pct.complete"/><DisplayName varRef="step.label“/><CustomCheck checkID="xx">
<Parameters><Return varRef="pct.complete" name="pct"/><Return varRef="step.label" name="label"/>
</Parameters></CustomCheck>
</ProgressInfo>
© 2005 Computer Associates International, Inc. (CA). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
CustomCheck
Add optional element ProgressInfo of type ProgressInformationType to CustomCheck