The resolution to Issue ALMAS14-9 introduced an error into the operation table. The type name was given an "ALMAS_" prefix, which is a PSM namespace convention and should not appear in the PIM.
The formatting of tables for operations for interface classes doesn't aid readability
The extra attribute mechanism is a useful extension mechanism for providing additional information and/or functionality relating to an alert. However, in the current specification there isn't a way to do this using predefined alert templates with runtime parameters.
Sequences of dynamic data and static message have been defined to be nullable in method RaiseAlertFromOverrides. As the sequence can have zero length this is an unnecessary level of indirection in the DDS/IDL PSM.
The specification does not standardise the logging mechanism. This could be achieved by PSM specific means.
The semantics of the reason attribute of the CallStatus call should be encapsulated as an enumeration. Also the formatting of the description of the attribute doesn't help clarity.
The description of ALMAS Manager does not give a clear picture of where it fits into the ALMAS system.
The spec does not appear to offer an interface for an alert client to be informed of the alternative or non-standard choice that has been made in response to an alert.
The DDS-Xtypes specification now provides a standard way of specifying keys. This specification should use that mechanism
The summaries for operations AttachCategorisationRule and DetachCategorisationRule refer to Categorization Rules. Whilst there is some description in section 6.4 there is no overview of purpose prior to this point or forward sign-posting to section 6.4, so the purpose of these methods is left somewhat opaque.
Topic types ALMAS_RegisterReceiver and ALMAS_UnregisterReceiver are not required as this functionality is covered by the statndard (DCPS) DDS Subscription Model.
Section 6.5 on Dynamic Behaviour would aid the understanding of the other parts of section 6, but it's existence isn't well sign-posted within the section. The roles of the interfaces declared aren't very clear with the sequence diagrams in particular needed to show where all the parts fit in.
Signpost behavior subsection from the start of section 6
Add an overview from the beginning of section 6 that introduces the PIM.
The specification appears to imply functionality that should be applied in the case of safety critical systems - ConfirmationRequired attribute of AlertData. This is in appropriate - the spec should do no more than offer this as an example use case for potential mitigation.
Remove references to safety criticality
Remove references to safety critical system design. Use of ALMAS should in no way be suggestive of contributing to a safety case.
The Summary Description for RemoveAlertsWithDynamicMessageData refers to a real world object being removed. This is just one reason for using this method; others exist. In general this is a method to remove all alerts that refer to a specific value.
Generalise description of RemoveAlertsWithDynamicMessageData
Make the removal of a real-world object an example of a more general principle.
The description of TimeoutAction attribute of Class AlertData describes its enumeration type rather than the attribute itself
Describe the timeout action attribute not the type
Replace text with a description of the meaning of the attribute with respect to the alert.
The features of the alert data model supporting multiple languages are not brought out well in the description. The description of static messages should discuss that there is intended to be one static message instance for each supported language variant
Clarify multi-language support in StaticMessage class
State that there should be one static message for each language supported
In describing the PIM structure, four packages are described plus an optional one (ALMAS Categorization). However in the detail one of the packages (ALMAS Configuration) is actually a class within the ALMAS Management package.
Describe as three main packages
Describe as three packages as presented in subsection 6.1, 6.2 & 6.3
The description of GetAlert would be improved by describing how the ID for an Alert is known
GetAlert gets current data for a known alert
The operation retrieves the current data for an alert already known to the client component. E.g. because that component raised the alert and stored the AlertID passed out, or the component received a notification about the alert.
It is not clear whether there are semantic differences between the events that trigger the ALMAS Client Callbacks ALMASNotificationListener and ALMASReceiver. The method summaries suggest that ALMASNotificationListener relates to safety critical alerts, but elsewhere in the spec this is only an example usage.
AlertDistributionNotification corresponds to Raised state
The AlertDistributionNotification should be triggered when the alert is in the Raised state (the first state for state machines in subsections 6.5.1 & 6.5.2).
Clarify that StateChangeNotifications are also generated for new alerts.
The Acronyms and Abbreviations section is missing entries - e.g. for PSM technologies such as DDS.
Add entries for acronyms from PSM
Add:
It is unclear whether the following are error conditions:
Duplicate template id with previous load
Unsupported variable type in dynamic message data
Unsupported type of data in alert data extra attributes
Mismatched tags between dynamic and static messages
Missing text for mandatory languages
Capacity limits exceeded
State error condition for load template set
The following are error conditions
For attribute TypeOfByteData in Class AlertDataExtraAttributes
Unclear whether or not strings should be null terminated.
Unclear whether only one or multiple int, float values etc. are valid for one instance of the class
Unclear whether the size of the value attribute not matching or being a multiple of the type from the TypeOfByteData attribute is an error condition
Clarify validity of byte data in AlertDataExtraAttributes
Strings are an array of UTF-8 characters without null termination
Multiple values of a particular data type are valid
The size of the value must be a multiple of the type of data unit size for Integer 16, 32 or 64
There should be a specific type (7) for media types. The description string should be the type / substype tree for media types.
The description of SetAlertInhibited says "... suppress or allow the raising of all alerts of that template"
This would suggest that calls to methods such as RaiseAlertFromTemplate for this template would subsequently fail (or succeed). An alternative interpretation is that these methods succeed but that Receivers ignore the corresponding Alert instance that is created.
For implementation interoperability it must be clear as to which of these designs to follow.
Fail attempts to raise alerts from inhibited templates
Implementations of the ALMAS Producer interface should fail attempts to raise an alert for a template for which SetAlertInhibited has been called (with Inhibited set to True). This effects RaiseAlertFromOverrides, RaiseAlertWithDynamicData & RaiseAlertFromTemplate.
The spec assumes "... that request IDs are generated by the caller and that they are unique across all ALMAS callers."
This assumption imposes system implementation specific behaviour on users of the ALMAS specification and reduces portability across ALMAS systems.
Request Uniqueness to be through Producer ID and Request ID
ALMAS Producers (Clients) already specify a combination of request_id and producer_id in their method calls to ALMAS Manager. Therefore as producer_Id is unique to a producer request_id should only need to be unique to a single producer (client). This is advantageous as it does not require management to (for instance) pre-allocate request id ranges to different clients.
A second consideration is that to apply the DDS Security model topic instance should be unique to a client so that each client is only permissioned for the data that relates to it. Therefore topic names should be post-fixed with the producer ID.
Operation SetLanguage is described as setting the language for a specific receiver. However the data model has the text for all languages (potentially) delivered to all receivers. Therefore it is unclear what the SetLanguage operation is supposed to achieve.
Resolve alert before delivery
Alerts should be resolved by the ALMAS Manager prior to delivery to each ALMAS Responder. In particular delivered Alert instances should contain a single static message instance and no dynamic data.
GetFilledMessageText doesn't have a language parameter so it's implementation is unable to determine which static message from a set to use as a basis for performing message text dynamic parameter substitution.
ALMAS Manager has knowledge of language selection
The ALMAS Manager has knowledge of any language selection for each receiver because of its SetLanguage operation.
Accordingly MessageText is resolved for each receiver and the filled (resolved) message text can be calculated and returned.
It is unclear whether it is an error for an Alert Template to be RaiseToAll and to have receivers and/or secondary grouping specified.
RaiseToAll error condition
State that when RaiseToAll is set it is an error to have Receiver Kind instances or a secondary grouping defined.
The summary for RemoveAlertsWithDynamicMessageData concludes with stating that implementation is optional. This is true for all methods in this interface - but is stated for only this one.
Also there is a rogue full-stop (period) in the text.
The ALMAS responder extensions do not have equivalent text either.
Remove implementation optional text
Remove the text that inconsistently appears for RemoveAlertsWithDynamicMessageData
The error condition on specifying an unsupported language for the alert is not described for the SetLanguage operation.
Include unsupported language error condition
Include error condition for completeness and portability. Map Reason to:
4 = Requested Service Unavailable
It is unclear whether it is an error condition to refer to a receiver before it has been registered or defined in a receiver hierarchy file. E.g. in an alert template configuration file, or when raising an alert (override or from data).
It is also unclear whether when registering a receiver it must match an entry in the hierarchy file.
It is also unclear whether it is permissible to call the LoadReceiverHierarchy multiple times and if so what semantics are expected.
Clarify Receiver Semantics
It is an error to refer to a receiver before it has been defined by load receiver hierarchy. (But receivers don't have to be registered - for instance a user with the relevant role may not have logged on to the system).
When registering a receiver it is an error for the receiver to not correspond to a hierarchy file entry.
Load receiver hierarchy may be invoked more than once per execution lifetime of ALMAS Manager, for instance by multiple producers to load a specific hierarchies for their needs. The semantics in this case are additive whilst disjoint: producers should define receivers in their own namespace; it is an error to define the same receiver in multiple hierarchies. Receiver instances may register themselves multiple times with receiver names from different producer namespaces.
Alternatively ALMAS Configuration maybe performed by a system function (entirely or in part). If entirely, the configuration operations are called once by the system function, producers don't invoke the configuration interface and receivers only register themselves once for the system defined receiver name.
Receiver Kind Type should be unique
Parent should have it's own Receiver Kind definition
Parent of a Receiver Kind should not introduce a circularity
Place additional restrictions on Receiver Hierarchy configuration schema
Receiver Kind Type uniqueness should be enforced using an xs:unique element within Receiver_Hierarchy_T acting on //Receiver_Kind/Type and scoped to itself (i.e. the hierarchy content).
Parents should be declared as Receiver_Kind elements containing the elements of which they are parents (their 'children'). This avoids circular dependencies as each name is then only used once and the relationships are structural.
'Parent-Child' isn't a great abstraction for this use case. Having inverted the relationships, 'priority receiver' would be better terminology. Therefore have each Receiver_Kind contain a Priority_Receivers element each with zero-or-more Receiver_Kind elements. Update the description for the file accordingly at the start of section section 7.3
Parent should have it's own Receiver Kind definition
Parent of a Receiver Kind should not introduce a circularity
The data model doesn't support multiple languages for the dynamic message data - but this is not made clear in the descriptive text.
Clarify concurrent multi-language support
Concurrent support for multiple languages can be achieved by using multiple instances of static message and dynamic message data; one per language and one per language-placeholder combination resepectively.
The summaries for operations AttachCategorisationRule and DetachCategorisationRule refer to Categorization Rules. Whilst there is some description in section 6.4 there is no overview of purpose prior to this point or forward sign-posting to section 6.4, so the purpose of these methods is left somewhat opaque.
Defer clarification on optional PIM
ALMAS Categorization is an optional PIM, therefore resolution is lower priority so for scheduling reasons resolution is postponed to a future RTF.
Topic types ALMAS_RegisterReceiver and ALMAS_UnregisterReceiver are not required as this functionality is covered by the statndard (DCPS) DDS Subscription Model.
Address issues requiring IDL changes in v1.4
For purposes of scheduling, a strategy of completing semantic clarifications and other minor typographic issues in v1.3 and moving to address issues requiring more substantive changes is proposed.
The spec does not appear to offer an interface for an alert client to be informed of the alternative or non-standard choice that has been made in response to an alert.
Address issues requiring IDL changes in v1.4
For purposes of scheduling, a strategy of completing semantic clarifications and other minor typographic issues in v1.3 and moving to address issues requiring more substantive changes is proposed.
The description of ALMAS Manager does not give a clear picture of where it fits into the ALMAS system.
Defer extensive document changes to v1.4
The role of ALMAS Manager with respect to the other ALMAS components should be clarified with reference to a set of behavioural diagram that describe how the various operations defined fit together.
For scheduling reasons this is best done for v1.4.
The DDS-Xtypes specification now provides a standard way of specifying keys. This specification should use that mechanism
Address issues requiring IDL changes in v1.4
For purposes of scheduling, a strategy of completing semantic clarifications and other minor typographic issues in v1.3 and moving to address issues requiring more substantive changes is proposed.
The extra attribute mechanism is a useful extension mechanism for providing additional information and/or functionality relating to an alert. However, in the current specification there isn't a way to do this using predefined alert templates with runtime parameters.
Defer interface changes to v1.4
For scheduling reasons this late-identified issue requiring interface code changes is noted and postponed to the next RTF.
The specification does not standardise the logging mechanism. This could be achieved by PSM specific means.
Defer extensive document changes to v1.4
ALMAS logging could be standardised by reference to a set of standard mechanisms in the PSM section, which refer to PSM specific method such as DDS serialisation standards.
This change would also be better made after removal of the obsolete DLRL PSM.
The formatting of tables for operations for interface classes doesn't aid readability
Defer large editorial change to a future RTF
The layout and syntax of the tables in the specification that describe the operations could indeed be much improved. However, such a resolution would have a very large editorial impact and with regard to scheduling it is proposed to defer this to a later RTF.
The semantics of the reason attribute of the CallStatus call should be encapsulated as an enumeration. Also the formatting of the description of the attribute doesn't help clarity.
Defer interface changes to v1.4
For scheduling reasons defer changes impacting IDL etc. to the next RTF
The declaration of the DynamicMessages field is incomplete and incorrect.
It is missing the DynamicMessages field name
It has an extra space in the type's package qualification
The type should be ALMAS_DynamicMessageDataTypeSet
Fix Issues with DynamicMessages field
Apply suggested changes from the issue
No space between sentences. Would be improved by inserting new-lines.
Also RaiseAlertWithDynamicData has an extra new-line.
Also RaiseAlertFromData needs a new-line instead of a space.
Improve Raise Alert Summary Formatting
Add improvements as suggested by the issue.
The Conformance section talks about general conformance level 1 functionality, but then adds extensions which are also numbered 1 to 4. There could be confusion as to what conformance to level 1 actually means.
Also a useful system could be composed of components that implement a subset of the core (level 1) interface. Therefore, there should be one or more additional levels of conformance defined that reflects this.
Basic, Advanced and Extended Conformance on an Interface Role Basis
There are three distinct roles in the ALMAS abstracted by the interface classes defined in the ALMAS Management package: Producer, Manager and Receiver. Conformance should recognise that a conforming application will be performing only one of these roles and therefore only a subset of the interface will be applicable.
Additionally, conformance should recognise a minimal basic level of conformance as a pathway to adoption and use of the specification. This is the set of methods to support raising and receiving alerts without templates, customisation or modification.
In the PIM the parameter for DynamicMessageDataSet in operations RaiseAlertFromOverrides and RaiseAlertWithDynamicData is StringSet, but in the CORBA and DDS PSM the type is DynamicMessageDataTypeSet (which is a sequence of the DynamicMessageDataType struct)
Re-align PIM for DynamicMessageDataSet
Change the PIM type to match the PSMs as the additional information in the PSM types is required to enable the required behaviour. Also align the parameter names (i.e. change to DynamicMessages).
There is no rationale for the DDS DCPS/IDL PSM topic type ALMAS_CreatedAlert.
By closer inspection, this is introduced to map to the AlertID out parameter of the various alert creation methods in the Producer interface.
It is needed so that producer know the alert id and are therefore able to cancel alerts that they have previously raised.
Add explanation of ALMAS_CreatedAlert
Add explanatory text to the ALMAS Management DDS DCPS/IDL PSM section
There is an erroneous space in the summary cell of RemoveAlertsWithDynamicMessageData
"specific rea l world object" should be "specific real world object"
Remove space in real
Remove space (this is only in the published spec not in the 1.1 RTF convenience doc)
In the CORBA PSM there are two operations with the name RaiseAlertFromOverrides but RaiseAlertWithDynamicData is missing.
Change second RaiseAlertFromOverrides to RaiseAlertWithDynamicData
In the CORBA PSM change the second occurrence of RaiseAlertFromOverrides to RaiseAlertWithDynamicData so as to match the PIM
The use of "pecking order" rather than prioritisation is unhelpful, particular if readers don't have English as first language.
Rework Pecking Order
Change pecking order to actionee prioritisation
"none standard" should be "non-standard"
Fix typo in AlternativeAction documentation element
none should be non
Attribute DataValue for DynamicAlertData has instantia-tion. This does not need to be split.
Remove hyphen
remove hyphen in description
Section heading is
OMG ORBA/IDL Platform Specific Model
should be
OMG CORBA/IDL Platform Specific Model
Add C for CORBA back
Correct Typo
The description of class DynamicMessageData and its DataTag attribute is ambiguous as to whether one or two percent (%) markers are required. Also the protocol is ambiguous when there are 10 or more markers. Also, particularly with a single % marker there isn't a defined way to escape the markers.
Clarify Dynamic Message Substitution
Placeholder tags to be designated by a single exclosing percent characters.
Multiple - in principle unbounded - replacements supported with each tag enclosed by space (or other non-alphanumeric character). The examples given in the current specification (t1, tn) are examples and more meaningful tags can be used and are encouraged (e.g. %number%, %score% or %name%).
It is not necessary to provide a means of specifying a way to express %name% as a literal substring in a static message as this would have no meaning to a system user.
Additionally, it should be possible to specify a replacement at the start or end of the static message. Equally it should be possible to have dynamic data at the start or end of the message and it should be possible to use punctuation around it (e.g. a comma). Therefore substitution points should be defined by:
(start | non-alphanumeric)%t(numeric){end | non-alphanumeric)
It is an error to specify static and dynamic data message instances with different substitution tags for the same alert template. In particular all static message instances (for different language locales) must have the same substitution set.
The description of the status attribute for class AlertData repeats the information for the Status enumeration. This is also poorly formatted and so difficult to read.
Remove duplicate information
Remove duplication of enumeration values for status attribute
Section 11 Changes or extensions required to adopted OMG
specifications applies to the submission and should not have been retained in the published specification
Remove section 11
Remove Section 11: Change or extensions required to adopted OMG specifications
This is missing an apostrophe and is in any case could be stated more clearly
Improve UpdateAlertPriority Summary description
Improve description to be "Updated the priority of existing alert instances that have previously been raised."
Refer to system components rather than system objects in first sentence
Change objects to components
Change objects to components in ALMAS Producer description
The Normative References is missing entries for the PIM and PSM technologies
Add new Normative Reference Section
Base style on TDAI normative reference section
Add references for DDS, IDL, GraphQL, COM, CORBA, XML
Extra hyphen in summary for UnregisterReceiver (avail-able)
Remove hyphen in UnregisterReceiver
remove hyphen in available
Add a GraphQL PSM option using the mapping defined in the TDAI specification for implementations using web technologies
Add GraphQL Platform Specific Model
Add a GraphQL platform specific model as an alternative technology particular aimed at contexts using this technology and other similar web technologies.
Base the PSM mappings on those defined for the TDAI specification, noting the principles of categorizing the PIM noted in the DDS / IDL / DCPS PSM.
The schema is to be added to the normative machine readable files.
The parameter for DynamicMessageData just has its type not the name of the parameter. ALMAS 11-11 was not specified correctly.
Add parameter name for RaiseAlertFromOverrides
Add parameter name DynamicMessageData for operation RaiseAlertFromData in DLRL PSM (error in ALMAS 11-11)
The PSM files for COM and DCPS have the same name and so the URLs become non-unique after applying ALMAS 11-2.
Supply new inventory file
Create new inventory file for all machine readable files with unique URLs consistent file the files' filenames
In the COM & DLRL PSMs RaiseAlertFromOverrides should be RaiseAlertWithDynamicData (erroneous fix for ALMAS 11-11)
Fix errorneous FromOverrides duplicate PSM operations
RaiseAlertFromOverrides operations in COM and DLRL PSM introduced by ALLMAS 11-11 should be named RaiseAlertWithDynamicData
RaiseAlertWithDynamicData has a long request_id parameter in the DCPS PSM instead of the new typedef
Use typedef in RaiseAlertWithDynamicData
replace long with the AlertIdType typedef
The schemas defined in the XSD PSM should use the https protocol instead of plain http.
Replace http with https in schemas
Replace http with https in schemas (Alert Data Template, ALMAS Configuration, Receiver Hierarchy & ALMAS categorisation rules) for the XML PSM
The goal of templates and dynamic data, i.e. encapsulating HCI design time information outside of code and then just supplying runtime variant data - e.g. track or other object identifiers - is undermined by the methods available. The only way to supply dynamic data allows everything to be overridden, which is intended to be the abnormal case. An in-between method that just allows dynamic data to be supplied would be a much more friendly interface for alert producers.
Create a RaiseAlertWithDynamicData operation
Add operation RaiseAlertWithDynamicData to class ALMASProducer in the Management PIM package - see updated diagram attached
7.3.5 p17 change first two sentences of paragraph 2 from
"Three mechanisms by which alerts can be raised are provided by the ALMASProducer interface class. Two variants RaiseAlertFromTemplate and RaiseAlertFromOverrides allow the system to raise an alert by simply specifying the alert ID, template ID and their own ProducerID, one of these also allows the over-ride of any placeholders that may be present in the ‘Message’ attribute of the alert data class associated with that template."
to
"Four mechanisms by which alerts can be raised are provided by the ALMASProducer interface class. Three variants RaiseAlertFromTemplate, RaiseAlertWithDynamicData and RaiseAlertFromOverrides allow the system to raise an alert by simply specifying the alert ID, template ID and their own ProducerID; with dynamic data allows the specification of the intentionally variable data to supplement the template alert definition; from overrides also allows the over-ride of any placeholders that may be present in the ‘Message’ attribute of the alert data class associated with that template."
7.3.5.1 p18 insert a new 3rd row to the table
Name: RaiseAlertWithDynamicData(String, int, int, StringSet)
Type: public CallStatus[Parameters]ProducerID: String,TemplateID: int,out AlertID: int, DynamicMessageDataSet: StringSet,
Summary: This will cause an alert based on a known alert template
to be created and raised, whilst only specifying the dynamic data content that differs from the template definition. All parameters are mandatory. Return parameter indicates success or failure reason.
9.4 p45
insert after declaration of RaiseAlertFromOverrides
ALMAS_DataModel::ALMAS_CallStatus RaiseAlertFromOverrides (
in string ProducerID,
in ALMAS_DataModel::ALMAS_TemplateIDType TemplateID,
in ALMAS_DataModel::ALMAS_DynamicMessageDataTypeSet DynamicMessageData,
out ALMAS_DataModel::ALMAS_AlertIDType AlertID);
10.3.2 p53
insert after declaration of RaiseAlertFromOverrides
struct ALMAS_RaiseAlertWithDynamicData
;
#pragma keylist ALMAS_RaiseAlertWithDynamicData request_id
10.4.2 p58
insert after declaration of RaiseAlertFromOverrides
ALMAS_DataModel::ALMAS_CallStatus RaiseAlertFromOverrides (
in string ProducerID,
in ALMAS_DataModel::ALMAS_TemplateIDType TemplateID,
in ALMAS_DataModel:: ALMAS_DynamicMessageDataType,
out ALMAS_DataModel::ALMAS_AlertIDType AlertID);
11.4 p67
insert after declaration of RaiseAlertFromOverrides
HRESULT RaiseAlertFromOverrides (
[out] ALMAS_AlertIDType *AlertID,
[in] BSTR ProducerID,
[in] ALMAS_TemplateIDType TemplateID,
[in] SAFEARRAY(ALMAS_DynamicMessageDataType) DynamicMessageData,
[out] ALMAS_CallStatus *CallStatus);
The optionality is not modelled in the PIM except for by way of explanation in the method's note.
The Boolean flags in the DDS PSM struct do not encapsulate the information well - in particular it requires a producer to default an only partially used data structure, unions would be better.
Use Optional IDL syntax in the DDS PSM
Describe mapping of implicitly optional attributes / parameters from the PIM in the PSM.
Use IDL syntax for optionality (i.e. @optional)
Several attributes in the PIM are typed as 'Enumeration'. The DDS PSM defines actual IDL enums for these with actual enumeration literals. The semantics of the literals are not defined there.
The implementation of these enumerations are not dependent on an implementation technology such as DDS and therefore should be standardised in the PIM - and properly documented.
Define Enumerations in the PIM
Add Enumeration classes for CategoryType, StateType, StatusType, ScopeType, TimeoutActionType and AckModelType to the PIM
IDL typedefs for ALMAS_AlertIDType, ALMAS_TemplateIDType & ALMAS_TimeoutType are introduced in the DDS PSM without explanation or correspondence with the PIM. Also the types are inconsistent: all int in PIM but long or long long in PSM. This should be consistent (and be so across all PSMs) and have rationale.
PSM Typedefs to be explained and consistent
ALMAS_AlertIDType is long for CORBA but long long for DDS
Make it consistent with other mappings of int from PSM and hence be long for DDS too.
Add explanation of Typedef introduction to PIM mapping discussion in section 9.1 (CORBA PSM rationale, referred to and followed by DDS PSM).
struct ALMAS_AlertDataAttributesType (that maps to Class Alert Data - naming difference is subject to another issue) is missing correspondence with attribute TemplateID and the (unnamed) aggregation to class AlertDataExtraAttributes.
Resolve by aligning with PIM
See linked proposal
The following issues should be discussed in the DDS PSM rationale section to be clear and unambiguous.
Define uniqueness of request ids and add compositions to mapping description
Request Ids are to be unique across all ALMAS participants.
The general UML mapping for CORBA and DDS PSMs is described in 9.1. It doesn't described composition explicitly, and should do so as per associations
The pairing of requests and responses is no action
The optionality of attributes is a duplicate
Class Alert Data in the Data Model PIM is mapped to struct ALMAS_AlertDataAttributesType in the DDS PSM; this has 'Attributes' additionally inserted into the name. For clarity in understanding the spec the name should be consistent.
Align DDS PSM struct ALMAS_AlertData with PIM AlertData class
rename ALMAS_AlertDataAttributesType to ALMAS_AlertDataType
add the other additional attributes from original definition of struct ALMAS_AlertDataType
remove original definition of struct ALMAS_AlertDataType
place new definition of struct ALMAS_AlertDataType where the original one was
The DDS DCPS PSM introduces a request_id parameter into each of the topic types for the ALMAS Management Service. However, it is defined as a "long long" in each case except one, ALMAS_RaiseAlertFromOverrides, where its just a "long". It should be consistently defined. It would also be a better abstraction if it had its own typedef defined in the PSM IDL.
Add Request Id typedef to IDL file
Add typedef declaration to ALMAS_Management.idl and use for all request id attribute declarations as per revised text for section 10.3.2
This struct contains
tring ReceiverID
rather than
string ReceiverID
Fix tring typo in IDL
tring should be string for attribute in struct ALMAS_AlertReportType
Issue ALMAS11-31 is wrong: http://www.w3.org shouldn’t have been replaced with https://www.w3.org in a <schema> definition.
Reverse ALMAS 11-31
Change https back to http in section 7 and the XSD PSM files
This has been missed from the DLRL PSM in defining the changes for ALMAS 11-5
Change type of parameter for DLRL RaiseAlertFromOverrides
Change the type of parameter Attributes from ALMAS_DataModel::ALMAS_AlertDataAttributesType to ALMAS_DataModel::ALMAS_AlertDataType
The file uses minInclusive and maxInclusive for a xsd:string restriction element instead of minLength and maxLength
Use min/maxLength for xs:restriction base for xs:string
Replace minInclusive with minLength and maxInclusive with maxLength in the Template Alert Data xsd PSM
The RaiseAlertFromOverrides optionality changes are to be applied to the actual PSM IDL file ALMAS_Management_DCPS.idl
Apply ALMAS 11-10 to IDL file
Apply changes to ALMAS_Management_DCPS.idl
Class Alert Data consistency changes need to be applied to the actual PSM IDL file ALMAS_Management_DCPS.idl as well as the specification.
Apply ALMAS 11-5 to IDL file
In ALMAS_DataModel.idl rename ALMAS_AlertDataAttributesType to ALMAS_AlertDataType add the other additional attributes from the original definition of struct ALMAS_AlertDataType and remove original definition of struct ALMAS_AlertDataType. Place the new definition of struct ALMAS_AlertDataType where the original one was.
request_id should have its own type in the PSM IDL file ALMAS_Management_DCPS.idl - i.e. ALMAS 11-4 changes should be applied to the actual file as well as the specification.
Apply ALMAS 11-4 to IDL file
Add typedef declaration to ALMAS_Management_DCPS.idl and use for all request id attribute declarations as per ALMAS 11-4
Filename is configured as DDS_common_IDL APM.idl, but ALMAS_DataModel.idl is logically the correct name and that expected by dtc/09-03-09 - DDS_DCPS_IDL APM.idl & DDS_DLRL_IDL APM.idl
Configure files with the correct name
Configure file currently with URL ALMAS/20090301/DDS_common_IDL APM.idl as ALMAS/YYYYMMnn/ALMAS_DataModel.idl
Configure file currently with URL ALMAS/20090301/DDS_DCPS_IDL APM.idl as ALMAS/YYYYMMnn/ALMAS_Management_DCPS.idl
Configure file currently with URL ALMAS/20090301/DDS_DLRL_IDL APM.idl as ALMAS/YYYYMMnn/ALMAS_Management_DLRL.idl
Section 7.3: The hierarchy is defined in the Receiver Hierarchy Configuration File and is alert independent, so for all templates the same. Therefore RKParentType should be removed from ReceiverKind related to AlertTemplate in order to prevent a lot of redundant information. Solution: Remove RKParentType from ReceiverKind related to AlertTemplate.Instead, introduce a seperate class ReceiverHierarchy. Note that this has quite an impact on the PSMs!
Consider Rationalisation of Receiver Hierarchy
Consider optimisation of the Receiver Hierarchy data structures
There is a comma missing after Cancelled in enum ALMAS_StateType
Add comma for Cancelled
Add missing comma after Cancelled in enum ALMAS_StateType in DDS_common_IDL_APM.idl
Alert_Template
Alert_Category
....
ConfirmationRequried
TimeoutAction
The enumerations in the XSD and the body are inconsistent.
See Timeout Action and Acknowledgement Model in the XSD and table 7.2.2.1
Pleas fix this form so it doesn't wipe data on verification errors and keep unchecking the agree box
Timeout Action:
7.2.2.1
XSD CancelOnly, NotifyOnly, CancelWithNotify
AcknowledgementModel
7.2.2.1
XSD AckByNone, AckByAnyone, AckByAll
Also inconsistencies in the element naming in that some use underscores between words and others do not
Alert_Template
Alert_Category
Secondary_Grouping
...
TimeoutAction
ReliablyDistributed
MessageText
...
The name implies that the alert has been distributed, however the description says: "...has been received..." and the sequence diagram also shows that that the alertDistributionNotification is called as soon as the alert command has been received by ALMAS. Proposed solution: Since the intention of the AlertDistributionNotification is to confirm receipt of safety critical alerts, it is logical to include the distribution of the alert because a receiver alert command may effectively not result in a alert. This could happen because it is inhibited or there are no receivers available in the system. Therefore, in Figure 6.7 (Page 30) move sequence 3.1.1 to 3.1.6. Alternatively, alert distribution could be excluded, renaming alertDistributionNotification into alertCmdReceived
Change text for AlertDistributionNotification , section 6.1.1, to be: "This is called as soon as a safety critical alert has been received by the ALMAS system. The onward distribution is notified through the StateChangeNotification callback."
ConfirmReceipt contains parameter ReceiverID. This parameter seems to be not neccessary since ConfirmReceipt of one Responder is enough to enter the Received state. Solution: Remove parameter.
Add to the description for Confirm Receipt of ALMASResponder in 6.3.6 "The ReceiverID field enables action & situation alerts to transition when sufficient confirmations have been received. 'Sufficient' is the 'actionee' for action alerts, and anyone for situation alerts. It can also be used for logging purposes.
Struct ALMAS_GetFilledMessageText: No way is defined to return the filled message text. Proposed solution: Define a new topic, called ALMAS FilleMessageText, containing request_id and filled messages.
Update IDL in section 9.3.2 to create a new topic called ALMAS_FilledMessageText which has a long long request_id and ALMAS_StringSet Messages.
Operation Operation RemoveAlertsWithDynamicMessageData: "RelatedObject Value" not defined in specification. Proposed solution: Replace "ObjectName: String" by "DataType: String" + "DataValue: String". These two together form the unique identification.
Proposed solution: Replace "ObjectName: String" by "DataType: String" + "DataValue: String". Also remove mention of RelatedObject from description. Affects section 6.3.4, 8.4, 9.4.2, 10.4
Section 6.3.6: RegisterReceiver: Parameter AvailableAlertReceiver.ReceiverKind.RKParentType can not be filled by the caller with useful information because it is not relevant here. Solution: Remove this parameter
See updated model, updated figure 6.3, change text for 6.3.6 RegisterReceiver as follows:
replace parameters to be ALMASReceiver, String, String
replace description as follows: This registers a receiver with ALMAS, the parameters are ReceiverHandle (for callback); ReceiverID (for use in all other methods, including UnregisterReceiver) and RKType to provide link to RK hierarchy.
Section 7.3: How can be indicated that a ReceiverKind.RKType has no ReceiverKind.RKParentType? RKParentType is a string (1 ..10) in which whitespaces are allowed. Solution: Specify that no ReceiverKind.RKParentType is indicated by only whitespaces in the string. Or change stringtype string (0 .. 10) for which string(0) indicates no ReceiverKind.RKParentType
Add to 6.2.9 description that a lack of a Parent is indicated by an empty string.
Operation RaiseAlertFromOverrides: "SecondaryGrouping", "Persistent" and "ReliablyDistributed" omitted. Proposed solution: Add "SecondaryGrouping", "Persistent" and "ReliablyDistributed".
Add in the additional parameters as proposed.
Operation RaiseAlertFromOverrides: "Message: String" not correct. Proposed solution: Should be "StaticMessageDataSet: StringSet".
Operation RaiseAlertFromOverrides needs to be able to set more than one message text and language. The proposal is to replace "Message: String" and MessageLanguage with a StaticMessageSet parameter.
Operation Unregister should be UnregisterReceiver
6.3.6 Replace operation Unregister by UnregisterReceiver.
Also update the IDL in 8.4, 9.3.2, 9.4.2, 10.4
Consistently start methods with capitals (or not).
Figure 6.1:
stateChangeNotification => StateChangeNotification
alertDataNotification => AlertDataNotification
alertDistributionNotification => AlertDistributionNotification
6.1.2:
stateChangeNotification => StateChangeNotification
alertDataNotification => AlertDataNotification
Struct ALMAS_AlertReportType: string AlternativeAction should be ALMAS_Stringset AlternativeAction
Update ALMAS Data Model IDL
We should be using the DCOM SAFEARRAY type instead of the UDT array types ALMAS_ReceiverKindTypeSet, ALMAS_DynamicMessageDataTypeSet, ALMAS_StaticMessageTypeSet, ALMAS_AlertDataExtraAttributesTypeSet.
Update the DCOM IDL in section 10.2 and 10.4
Section 6.2, 7.1: Name inconsistency: AlternativeAction in section 6.2 is Alert_Responses in section 7.1. Solution: Use the same names.
Use AlternativeAction in 7.1
Issue: Type of element name "Tag" not correct. Proposed solution: Type should be string instead of integer.
Tag element type should be string not integer. XML in section 7.1to be updated
Hierarchy, as can be specified according the Receiver Hierarchy Configuration file is alert (Template) independent. Is this not too restrictive? Solution: Enable receiver hierarchy per alert template?
No Data Available
_put_ALMAS_SystemID - parameter changed to "in out" instead of "in" because of compiler limitation for parameter type BSTR.
GetFilledMessageText - parameter MessageText changed to "in out" instead of "out" - compiler limitation for type BSTR.
Remove put_ALMAS_System_ID this is not intended to be alterred by the ALMAS user.
Sections 2.8.11 & 2.8.1.3 LPSTR types should be changed to BSTR (automation type).
Agreed - this affect the DCOM IDL files in sections 10.2, 10.3, 10.4.
Section 2.6.1.3, 2.3.3.5.1 & 2.7.4.2 Method RaiseAlertFromOverrides - optional parameters are not supported in C++ as defined in version 7 page 37 for this method. 'Optional' parameters can be supported if the parameters are changed to pointers. Parameters that are not required can then be passed in as NULL.
Propose that the method is amended to include a 'valid' indicator for each optional parameter in the PSMs.
Sections 2.6.1.2 & 2.8.1.2 - Inconsistent naming of the Call Status parameter. Some methods define it as CallStatus, others as Status. Suggest we change methods which define the parameter as Status to CallStatus.
Carry out the change for section 8.3, 10.3, 10.4 as in attached IDL. For section 6.1.1 remove Status from the parameters
the format of this string needs to be specified so that different products can parse it consistently and thus can interoperate.
Clarify format of the string.
Update 6.2.10 table description for MessageText:
This is a text string, which in an Alert or AlertTemplate is only partially completed. With the MessageText being "xxxxx %t1 yyyyyyy zzzz" in an Alert or AlertTemplate, and with a DynamicMessageData with DataTag having the value 't1' and DataValue having the value '123' then the resulting MessageText in response to GetFilledMessageText will be 'xxxxx 123 yyyyyyy zzzz'. All substitution points are bracketed by use of "<space>%" and <space>, and are case sensitive, alphanumeric strings ("t1" in the above) which should correspond to a DataTag in an associated DynamicMessageData.
Update text for DataTag in 6.2.8:
This identifies the insertion point for the related object in the MessageText associated with the Alert. I.e. where the MessageText is "xxxxx %t1 yyyyyyy zzzz", then DataTag has the value 't1'. It is a case sensitive, alphanumeric string
This section provides an extension mechanism for AlertData so that this data can safely be transferred to products that don't understand the extensions. The requirements that receipt of any of this data not be "dropped" etc. need to be clarified. Also, there should be the possibility for providing a "type" indication (possibly either a string or enumeration) that would allow different products to interpret different extensions.
Need to update Figure 6.2 and 6.2.3 AlertDataExtraAttributes attributes table:
1) add attribute "TypeOfByteData" of type int, with the description of
"Valid values for this are:
0 = string
1 = Integer8
2 = Integer16
3 = Integer32
4 = Float32
5 = Float64
6 = bytes"
2) add attribute "Description" of type string with description "Used to provide indicaton of the content e.g. "image (jpg)", "URL", "track object", ..."
Replace the last sentence of the AlertDataExtraAttributes description
'The extra attributes are configured via the ALMAS Alert definition xml PSM specified in section 7.1. If defined in the Alert definition XML provided to ALMAS, then ALMAS shall support the definition, receipt, storage and passing of this data to receivers as part of a standard implementation.'
ALMAS Client Callbacks (comment on a previous version that has not been addressed) Package names or parts of the package names are reused and redundant within the class name. Examples include ALMAS::Client Callbacks::ALMASReceiver and ALMAS::Client Callbacks::ALMASNotificationListener
Removed the redundant names. Replace section 10.3 with the following IDL (changes annotated with comments):
The text for the attribute CurrentState implies that there is a constraint between the allowed values and the category of the alert. These constraints need to be formally captured, e.g., through OCL.
Update the model as described below and the text in section 6.2.1.:
1) give a name to association between Alert and Alert Data on AlertData end of "alert_data"
2) include an OCL constraint for this: "context a: Alert inv: if ((a.alert_data.Category = Information) or (a.alert_data.Category = Warning))) then (a.CurrentState <> Handled)"
Documentation changes required to section 6.2.1 description for current state in attributes table to append 'Note that Handled is not a valid state for Information and Warning Alerts.' Figure 6.2 requires update to show the constraint.
The description of Alert has the text: "The message text is not fully filled in here." This looks like an editorial comment.
No Data Available
Add an extra optional parameter in Dynamic_Message_Data_T "Max_Text_Length" for the Text variable data to aid sizing the final text when attempting to expand the dynamic text.
No Data Available
Current schema only allows one Alert Template per XML file. Correct to allow more than one alert.
No Data Available
the descriptions of the model elements are not sufficient. For example, the description of ALMASNotificationListener is "Class provided by registering notification listeners for receipt of alert distribution notifications", which is not much more descriptive than the name of the class
Included significantly more descriptive text in the model section of the specification. Section 6, 6.1, 6.2, 6.3 affected significantly. Edited text supplied as additional change-barred document, attached. Note that this issue should be applied FIRST, there are some additional changes to the text in section 6 which should be applied after this issue.
It is real error that there is no relationship (including possibly a derivation) between AvailableAlertReceiver and ALMASReceiver. A link by a string name doesn't allow type-safe technology to check the proper provision of a ALMASReceiver as a available receiver.
No change to the model has been made. The following additional text has been added to section 6.2.6 (as part of resolution of issue 12290): ' through the ReceiverID attribute, which is provided at registration time to ALMAS using the RegisterReceiver method.'
Each of these operations, in fact, only work with an XML file that conforms to a particular XSD, which is defined later in the specification. This needs to be made explicit
6.3.1 table row entries need updating to reflect the XML file linkages.
Replace all text in section 2 of beta 1 with the following revised text.
This section seems to be misplaced. It is a table without headings or other explanations
No Data Available
Topic GetFilledMessageText needs ReceiverID attribute because a ReceiverID may set a specific language (Topic ALMAS_SetLanguage). Proposed solution: Add attribute ReceiverID to topic GetFilledMessageText
Update IDL in section 9.3.2
In the PIM, when creating an Alert ( RaiseAlertFrom...) it is required that the created Alert is returned as an out parameter (AlertID). This is omitted in the DCPS PSM. Here only the result in terms of successfull/not successfull is returned by means of a topic. Note that the created AlertID might be needed by the ALMASProducer for subsequent calls. Proposed solution: Define a new topic, called ALMAS CreatedAlert, containing request_id and AlertID.
Update IDL in section 9.3.2
ALMAS configuration files contain not valid xsd constructs. E.g. Alert_Definitions.xsd/24-01-2008: xs:restriction not terminated. ALMAS_Categorisation.xsd/23-01-2008: space chars invalid in some attributes. ALMAS_Hierarchy.xsd/24-01-2008: invalid characters (--) in element. Solution: Validate configuration files with appropriate xml editor.
XSD files validated.
2.8.1.3 _get_ALMAS_SystemID,GetAlert,GetAlerts, GetTemplate and GetTemplateIDs - cannot return data directly. Will need to be returned from additional callbacks on the appropirate interfaces, so out parameter now removed and replaced with an input parameter to pass in the receiver's handle.
This affect the DCOM interface for ALMAS Notification Listener in section 10.3
Attribute TimeoutAction: There seems to be no way to inform somebody about a timeout. Solution: Enable notification by ALMASReceiver.stateChangeNotification(int, Enumeration) and adding Timed_Out to the enumeration.
Change 6.2.1 description for CurrentState to include "Timed_Out" after "Cancelled"
Is the priority attribute value independent of the category meaning that an information alert can have a higher priority than a situation alert?
Add to 6.2.2 description for Priority "the priority is open for client use and not intended for interpretation by ALMAS."
By means of RaiseAlertFromData an alert can be raised that is not present in the ALMAS template database. However, receivers (ReceiverKind, see Section 6.2) can only be associated with templates. How can receivers now be defined? Solution: Include parameter AlertReceiverSet: StringSet (as with RaiseAlertFromOverrides)?
To reduce the complexity of this the approach taken is to change the AlertData parameter type to be an AlertTemplate parameter - this is not read or initialised from the XML, so the TemplateID field is invalid, but it reduces the complexity of the interface significantly.
Method GetAllTemplateIDs of ALMASManager not mapped. Solution: Map to: DDS read with query condition.
Add to table on page 59 one row below method GetTemplate:
"ALMAS Manager - GetAllTemplateIDs (String, TemplateIDSet) - DDS read with query condition"
It would be better to map a number of methods, which are now directly mapped on DDS level constructs, on control topics because of two reasons: 1. Without control topics a producer can not be directly notified of a producer or system related error/problem. E.g. when a producer produces a new alert, he can not be notified that this was not succesfull because no active receivers are present. 2. Much more important: An alert contains ""static"" information but also state information (e.g. AlertId, Currentstate, Receivers etc.). Only ALMAS should be allowed to maintain this information, not a producer. Because a producer can now write a complete Alert, it may also write state information. This would violate data hiding principles and therefore ALMAS would be unnecessarely complex and obscure. Solution: The following methods should map on control topics: 1. UpdateDynamicMessageData 2. SetAlertInhibited 3. RemoveAlertsWithDynamicMessageData 4. RaiseAlertFromOverrides 5. RaiseAlertFromData 6. UpdateAlert
Remove the following items from table in section 9.3.2:
ALMAS Manager - UpdateDynamicMessageData
ALMAS Manager - SetAlertInhibited
ALMAS Manager - RemoveAlertsWithDynamicMessageData
ALMAS Producer - RaiseAlertFromOverrides
ALMAS Producer - RaiseAlertFromData
ALMAS Producer - CancelAlert
Add the following new topics ALMAS_UpdateDynamicMessageData,
ALMAS_SetAlertInhibited, ALMAS_RemoveAlertsWithDynamicMessageData , ALMAS_RaiseAlertFromOverrides,
ALMAS_RaiseAlertFromData,
ALMAS_CancelAlert
to DCPS IDL
For the purpose of these new topics, note that attributes are removed from struct ALMAS_AlertDataType and now contained in new struct ALMAS_AlertDataAttributesType.
RegisterReceiver mapped on DDS creation of a new listener/data reader (of topic ALMAS_Alert). ALMAS must know which ReceiverKinds are active in the system at a certain moment. For example which roles are played that are interested in alerts. A (future) Role management system will not export such a relation because it will not import ALMAS particulars. Worse, it is not even able to do so because in OpenSplice it is not possible to determine which listeners are present for a certain topic. Even when that would be possible, there is no way to relate listeners to e.g. roles. Solution: For registration declare a new topic containing a RKType?
Remove ALMAS Responder - RegisterReceiver from table in section 9.3.2.
The number of DynamicMessageData instances is fixed for an Alert(Template). This means that for a specific Alert only a fixed maximum number of tags can be used. When you want to raise an alert like "Tracks present in an area", this number should be dynamic.
Remove the number limitations of items Static_message, Alert_Data_extra_Attributes, Dynamic_Message_Data, Alert_Routing from the Alert_definitions.xsd file and item Receiver_Kind from the ALMAS_Hierarchy.xsd configuration file.
Note that also fixed string lengths as defined in the configuration files are unnecessarily restrictive and should be removed.
Catgorisation rules must be defined offline by means of the "ALMAS categorisation rule file". Rules can be attached and detached to alerts by means of methods "AttachCategorisationRule" and "DetachCategorisationRule". An alert can only be attached after it exists, so after it is raised. However, the intention of categorisation is to do an action (e.g. raising an alert) according to a condition on occurence of an event. There seems to be a chicken-and-egg problem. Solution: Attach/detach AlertTemplate instead of Alert?
Update figure 6.3 and section 6.3.4 - Use TemplateID instead of AlertID as parameter for both Attach and Detach methods. Change alert to AlertTemplate in both descriptions.
Update IDL for these methods.
Removal of alerts is not clearly addressed in the spec. Should be addressed explicitly. Solution: Alerts are removed as follows: . For all alert categories holds that they are removed when cancelled by the producer. . Information and Warning alerts: Removed when an acknowledge is required and the appropriate acknowledge is given or when a timeout is defined when the timeout is expired or when no timeout is defined a general (adaptable) timeout is assumed. . Action alert: Removed when HandleAlert is called by all addressees. . Situation alert: Will not be removed when HandleAlert is called by all addressees. Will only be removed if cancelled by producer.
Covered as part of issue 12290 response.
For clarity the updates to section 6.3 are repeated here:
· For all alert categories, an alert is removed when cancelled. Note that Situation alerts are only removed when cancelled.
· Information and Warning alerts are removed when the required number of acknowledgements (as identified in the AlertData AcknowledgementModel attribute) are given or (if a timeout is defined) when the timeout is expired.
· Action alerts are removed when HandleAlert is called by the Receiver identified as the Actionee in its AlertReport.
Figure 6.5, page 28: wrong picture (same as next one). Solution: Copy correct picture from document c4i/2008-02-01
Copy correct picture and update figure 6.6 to same style.
Sections 2.6.1.3, 2.7.4.2, 2.8.1.3 Query - Method UpdateDynamicMessage takes in OldValue - why?
No change to model
Add the following to UpdateDynamicMessageData description in 6.3.3:
"OldData is necessary in order to clearly indicate which dynamic message data should be changed."
Added prefix "ALMAS_" to enums to avoid conflict with existing definitions within our system.
This is only necessary for the DCOM mapping and affects IDL in section 10.2 only
UpdateAlert:By means of an UpdateAlert a producer can update an already raised alert with new AlertData as parameter. Two problems here: 1. The producer may change all attributes of the AlertData making this very complex to realise. However, most, if not all attributes, are not likely te be changed. 2. The alert may already be partly (by some addresses) handled making the realisation even more complex. Solution: UpdateAlert not useful, so remove it from the spec.
Reduce the scope of UpdateAlert to cover the change of priority and rename to be UpdateAlertPriority. Update figure 6.3, section 6.3.5 and the management IDL files
ALMASReceiver.stateChangeNotification(int, Enumeration): The values of the Enumeration are not specified. Solution: Same enumerations as for Alert.CurrentState.
Add to 6.1.2 the following "These states are the same states as used in CurrentState for an Alert."
