ALF 1.0 Requirements Document
These requirements have been approved for ALF version 1.0 by the ALF requirements committee.
ALF Event Broker (AEB) Requirements
Requirement AEB1 Events must include standard data
Description: Events must include a standard set of data about the event, to include Event ID, Event Type, Event Context and Entity Information. Event Context must contain information that will allow the ALF service flow to contact the tool in order to get additional information. The exact format of event context information will be tool specific. Entity information will include the data necessary to identify the ‘type’ of the object, if any, that caused the event. For example, if the event is ‘entity added’ the entity information might be ‘defect’ indicating that it was actually a defect that was created rather than a, for example, build request. The exact format of the entity information will be tool dependent, but the ALF conformance guidelines should define a starting set.
Requirement AEB2 Event ID passed by source to AEB
Description: The event ID must be generated by the event source and will be passed to the event broker when the event is raised.
Requirement AEB3 Event ID must be unique
Description: The event ID must be unique across ALF so any single event can be traced, through its ID, back to the event source. The ALF project team will make recommendations for tools that can be used to generate unique Ids.
Requirement AEB4 Event to include extended data
Description: Events must be associated with an event structure that defines, at design time, any additional parameters passed by the event source to the event broker.
Requirement AEB6 AEB to support multiple parallel independent service execution
Description: The event broker will enable 0…n fire and forget service flows to be triggered as a result of any single event being received by the event broker. These service flows will be mutually independent.
Requirement AEB7 AEB uses Fire-and-forget service invocation model
Description: The event broker will use a 'fire and forget' model to start service flows. The service flow return values, if any, will not be available for use by the event broker or the event source.
Requirement AEB8 AEB to allow custom event filtering.
Description: The event broker will provide a SPI allowing users to define custom event filtering based on values passed to the event broker within a custom event structure. For the POC we will not use any filtering.
Requirement AEB11 AEB log events received
Description: The event broker will log all received events. At a minimum, the event broker will log a timestamp, the event ID, event source information, event type and the context information.
Requirement AEB12 AEB log services started
Description: The event broker will log every service flow started.
Requirement AEB15 AEB should allow logging levels for debug logging
Implemented: Partial in M7 TBD
Description: Note: this needs either to be cumulative or selective. TBD based on research by JS.
If the user has specified debug logging, the event broker will log the arguments passed into the service - moved from AEB12 [TGB]
The ALF event broker will allow users to specify a default logging level. By default the AEB will log events as specified in AEB11. By default the log will include all errors, a record of all events received and a record of all services started. The AEB may write additional log entries depending on the logging level the user has set.
Debug: If the User specifies debug logging, the AEB will log the entire contents of the event structure passed in to the AEB by the event source, and other information that is available and helpful. (The exact contents will be defined at design time rather than during requirements time.) The AEB will also log any informational and warning messages generated by the AEB.
Information: If the User specifies an informational logging level, the AEB will log any informational and warning messages, but will not log debug messages.
Warning: If the user specifies warning logging level, the AEB will log warning messages in addition to the default messages, but will not log informational or debug messages.
Error: This is the default logging level and includes events received, services started and errors. If the user does not specify a default logging level for ALF, the AEB will assume Error logging.
None: This turns off logging completely.
Requirement AEB16 AEB will log all errors
Implemented: Partial M7 TBD
Description: The ALF event broker will log any errors detected while during its normal operation. Error messages will include a timestamp and an event ID, together with an informative message describing the error. These messages will be written only if errors are turned on in logging.
Service Flow Engine Requirements
Requirement SFE1 Service Flow Engine to accept a standard set of parameters
Description: Every service flow must accept a standard set of inputs passed in from the event broker, to include Event ID, Event Type, Event Context and Entity Information.
Requirement SFE2 Service Flow to accept an extended set of parameters
Description: Every service flow must accept an extended set of inputs, defined at runtime, passed in from the event broker.
Requirement SFE3 Service flow can be started independent of the event broker
Description: A service flow must be start-able from either the event broker or independent of the event broker. It falls to the caller to conform to the service flow calling interface.
ALF Security and Role Requirements
Requirement ASR1 Credentials accepted by all strongly ALF enabled tools
Description: ALF credentials generated or passed by one strongly ALF compliant service must be recognized by all other strongly ALF compliant services. It is up to the individual tool to verify authorizations for the user represented by the credential.
Note: The ALF requirements committee has said that requiring services to be strongly ALF compliant sets the bar too high for tool participation. Therefore, this requirement is valid only for those services claiming to be strongly ALF compliant.
Requirement ASR3 ALF to provide credential generating tool
Description: ALF must provide tool vendors with an algorithm or a library enabling the tools to generate their own credentials. Web services that are strongly ALF enabled must accept these credentials.
Requirement ASR5 Credentials not necessary for weakly compliant web services
Description: ALF should not set the bar too high for vendor tools to participate in ALF service flows. ALF must not require that vendors' web services must be modified to accept ALF credentials.
ALF will support these use cases:
Vendor whose services are not strongly ALF compliant can still participate in ALF service flows, but their security must be managed by the service flow designer. While not exhaustive, the following describes several alternatives.
- The vendor can configure the services to accept all service requests without security validation. We do not recommend this option.
- The service flow designer can elect to hard code credential information in the service flow. For example, if a vendor requires a userid/password be sent in as parameters to a web service, the service flow designer can hard code the userid/password into variables within the BPEL engine, to be then passed to the service. We do not recommend this either.
- The service flow designer can define an ALF user whose credentials will be accepted by all services participating in the service flow. This is probably an OK solution as long as the ‘real’ user information is captured somewhere.
- The service flow designer can accept tool-specific credentials as arguments to the service flow. Only recommended if the credentials can be passed securely.
- The service flow designer can implement a custom SSON solution.
All of these alternatives have problems. First, there is very little security when userids/passwords are encoded within a service flow. Second, all user related audit information will be lost since a common user will be used to perform all of the actions.
Nonetheless, some alternative of this sort must be used by the service flow designer for services that are not strongly ALF compliant.
ALF Web Services Requirements
Requirement AWS1 Strongly ALF compliant Web Services must accept credentials
Description: All calls to web services within ALF service flows must recognize credentials if they are ‘strongly’ ALF compliant. Move ASR1 to here.
Requirement AWS3 UDDI is a very low priority for ALF
Description: UDDI need not be delivered or required as part of ALF 1.0. We can specify in a best practice document that UDDI is recommended for ALF implementation sites with complex and varied tool sets.
Requirement AWS4 Vendors are not required to write web services specifically for ALF
Description: It would be setting the bar too high to require that vendors write web services specifically for ALF. While we may define conformance guidelines and best practices for these services, any service with a WSDL contract that can be called from the users BPEL engine will be allowable in an ALF service flow. Web services that don’t conform to ALF security and SSON guidelines are considered to be ‘weakly’ ALF enabled. Security and role enforcement must be implemented by the service flow designer for any web service that is weakly ALF compliant.
Requirement: AWS5 AEB provide service to raise event
Description: The event broker will expose a service allowing external tools to raise ALF events. These events may also be raised within the event broker itself.
Requirement: AWS6 AEB to provide event id generating service
Description: The Event Broker will expose a service allowing external tools to ask for a unique event ID.
Requirement: AWS7 Service Flow Engine to provide logging service
Description: The Service Flow Engine will provide a service allowing a flow designer to put in custom logging steps. The log entries resulting from this service call will be similar to the log entries made by the AEB and will be written to the same log configured for the AEB.
The service must allow the caller to specify a logging level of Debug, Informational, Warning or Error. If no level is specified, the service will assume the message is informational. The messages will be logged based on the rules defined in AEB11 – AEB16.
Requirement AWS8 ALF to provide credential generating service
Description: ALF must provide a service allowing tools to generate credentials that may be accepted by vendor web services if those web services are 'strongly' ALF enabled.
Requirement AWS9 ALF to provide a service to generate an official ALF timestamp for clock synchronization
Description: This service will provide an official ALF timestamp that can be used to synchronize tool logs with ALF logs.
Requirement AWS10 ALF to provide a default compensating service
Description: This service will provide service flow designers with a default service for handling compensating. This service will write an error message in the log to include a timestamp, the event ID and a description of the problem. (Note: this may not be possible since the service flow designer will be responsible for defining compensation boundaries within the service flow. (This is TBD.)
ALF General Requirements
Requirement AGR1 Section 508 Compliance
Description: All ALF user interfaces must be Section 508 compliant.
ALF Administration Requirements
Requirement ADM1 Admin GUI required for the POC
Description: ALF need not provide an administrative GUI for the POC. Configuration files may be used to specify the administrative settings for ALF in the POC timeframe.
Requirement ADM2 Admin GUI required for ALF 1.0
Description: ALF will require an administrative interface for version 1.0. This interface will allow users to - Browse the list of available events that can be associated with service flows - Browse the list of available service flows that can be associated with events - Define associations between events and service flows - 'Publish' service flows from edit to production - Define filters to specify when events trigger service flows Derived requirement: ALF will allow administrators to perform the above functions.
Requirement ADM3 Protections around administrative functions
Description: ALF version 1.0 need not include password protections for administrative functions. ALF 1.0 can make use of protections provided by the native OS.
Requirement ADM4 ALF to provide start/stop scripts
Description: ALF version 1.0 will include scripts or utilities that will start and stop the ALF event broker and the BPEL engine. We will configure the script/utility to work with the BPEL engine from the delivered example implementation, and will include instructions for configuring the script/service to work with other BPEL engines.
Requirement ADM5 ALF to allow process developers to define custom event structures
Description: ALF must allow process designers to define custom event structures, derived from the standard or vanilla ALF event structure, so the ALF event broker can map events to event structures, and so the event structure can be passed through to the BPEL engine.
Requirement ADM6 ALF to allow administrators to enable enhanced logging level
Description: ALF must allow an administrator to specify a default logging level that will be applied to the AEB. The levels are Debug, Informational, Warning and Error. The’ default’ default is Error, and is defined in AEB15.