Capability (C014):— messaging

The two purposes of messaging are firstly to provide meta-data about a PLCS exchange and secondly to be able to record an audit trail relating information to its transfer between PLCS systems. It covers two functions: Envelope provides the audit trail of transmission, while Message describes the data transmitted and the reasons for sending the information.

The need for an audit trail of transmission may arise from both commercial and technical considerations. For example, legally, there may be a need to show that contractual commitments have been met or, in the context of product liability, show that the recipient had been warned that a problem exists (and is therefore liable for the consequences). Technically, there may be a need to ensure that the recipient gets all the data but only once, for example, when a subcontract is extended, then the subcontractor needs the data relating to the extra work, but not the original data, which they may have already updated. Envelope records the audit trail of transmission, however it is a business decision whether such an audit trail is needed, and if so, whether it is simple logged externally to the system or whether it needs to be directly linked to the data.

Message is provided to handle meta-information about the data. This meta-information can include:

Although Messaging provides a single data structure linking information to its exchange, some care is needed in its use. A Message is defined as an historical record of an interchange between systems. This means that, if historical accuracy is required - say, for legal reasons - then the data it references should not change. Therefore the data should be recorded separately from the working database. If a snapshot of data is required, Document should be used, and the meta-data applied to it.

Message references data through an "escape" mechanism that allows it to directly reference any STEP entity and this mechanism can be extended to reference any type of data. Within a PLCS DEX, the usage of Message is restricted to referencing the key element of a DEX data set.

Message can provide support for the automatic processing of the its contents. For example:

Since the business requirements for automatic processing will vary widely, Messaging provides only a set of basic classes, often as place holders which will need to be extended through exchange agreements.

Information model overview

This section provides an overview of the information model that supports this capability.

The main entities are Envelope which provides an audit trail of transmission, Message which provides the context for the contents, and Content_item which provides the mechanism to link the Message to its contents. The items pointed to from Content_item are left blank apart from an instance marker and are linked by curved, dashed arrows, to emphasis that the reference mechanism used is not a relationship in the EXPRESS sense of the term. Rather, an escape mechanism is used, in order that the Message can reference any and every STEP entity.

The required characterizations of Envelope are the sender, a list of addressees and the time and date when it was sent. The transmission of the Envelope may be approved. The Envelope could also record properties about the Envelope and its contents, such as encoding, but this beyond the current scope. Envelope_relationship allows envelopes to be related to each other, and is used to associate an Envelope to its acknowledgement.

Envelope

An Envelope is an historical record of the transmission of a Message. It is used to record the audit data for sending and acknowledging a Message. In practice, Envelope should never be instantiated in a PLCS DEX transmission, since it records the process of sending the DEX. Rather, the information is abstracted from the transmission system, and may be stored by sender or the recipients as part of their audit trail.

Because it is an historical record, each Envelope is only used once, and so not versioned. Since the sender's actual address is derived from the transmission system (e.g. e-mail address), it may not correspond to the formal sender of the Message.The sender must be uniquely identified across the PLCS environment used, and is either an Organization or a Person_in_organization. In the case of the sender being a system, the system will be treated as an Organization, possibly related to the Organization owning it. The id together with the sender uniquely identify the Envelope and there is an obligation on users of Envelope to ensure this. Note, since the identifier and sender are derived from the transmission system, Messaging does not use the Identification Capability for envelope identifiers.

Figure 2 is an instance diagram for a typical Envelope with two recipients. The Organization is assigned in one of the roles [Actual_sender]

Error RDL1: The class Actual_sender does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
, [Actual_recipient]

Error RDL1: The class Actual_recipient does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
or [Actually_copied_to]

Error RDL1: The class Actually_copied_to does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
, in the usual sense of the terms. Date_time is assigned in the role [Date_envelope_sent]

Error RDL1: The class Date_envelope_sent does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
. The recommended practice for Envelope is that Date_time be used rather than Calendar_date, since the sequence of transmissions within a single day may be significant. The recipient may also assign a Date_time with the role [Date_envelope_received]

Error RDL1: The class Date_envelope_received does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
.

An Envelope may also be used to request a receipt and to send one. The exact semantics used to acknowledge the reception of a Message is described below in the section Meaning of Acknowledgements. Figure 3 shows an instance diagram for a simple request/acknowledgement. The main elements of the original transmission are coloured blue, that of the reply green.

The "original" Envelope (id = 123) contains the Message, and has the sent Date_time, the Person_in_organization who is the sender (David Welsh) and another who is the recipient (George English). The acknowledge attribute has the value "ask message arrival".

The acknowledgement consists of the Envelope used to reply - this has the acknowledge attribute set to "acknowledge arrival" - together with the common elements and their associated assignments. It also includes the original Envelope, as this carries its identifier, however it does not include the Message or any of its assignments. lf one were to actually send the acknowledging Envelope, then the file would contain only the Envelope entity from the original Message, the acknowledging Envelope, and the organizations and dates with their assignments to the acknowledging Envelope (but not the assignments to the sent Envelope).

The final piece in the instance diagram is the Envelope_relationship, which associates the original Envelope to the acknowledgement. Its role is[Acknowledges]

Error RDL1: The class Acknowledges does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
defined through reference data. This entity need only be constructed within the audit database, and is not part of a transmission.

It must be stressed that in terms of a PLCS database, an Envelope is an audit trail element, and should not appear explicitly in a DEX transmission. Further, the acknowledgement structure allows for the actual Message being garbled and unreadable, and so transmission data must be derived from the system not the transmitted content.

As an Envelope is an historical record of something that has occurred, it may not be changed once instantiated.

When an Envelope is sent normally, it must contain a Message, however when it is sent as an acknowledgement, it may not contain a Message.

Meaning of Acknowledgements

The Envelope provides for two levels of acknowledgement, "Message received" and "Message read". There are potentially three separate semantic contexts for this:

The precise operational semantics of the data distribution/e-mail system is outside the scope of this standard, and historically has varied from system to system. (The interested reader is referred to the technical discussions on harmonisation between SMTP and X400 as an illustration.)

In a legal and contractual framework, the function of "ask message arrival" may be used to provide evidence that the sender acted in a timely manner and had ensured that the information had be delivered. The function "ask message read" may be used to show when the recipient was aware of the content of the message. It is the function of the contractual framework to give precise legal meaning to "delivered" and "read", and provide the audited processes which show that these replies are given only at the correct point in the process. This is outside the scope of Messaging.

This standard defines the meaning of the acknowledgements only in terms of the operational semantics of a distributed PLCS system. "Message arrival" means that the recipient has a stored copy of the Message, and that sender has no need to retain a copy of the Message. For example, if the sender is a data logger with limited storage capacity, "message arrival" says, in effect, that it is safe to overwrite the existing data.

"Message Read" has the meaning firstly that the content of the Message has passed any validation checks that the recipient applies, and secondly, that the content of the Message has loaded successfully into the recipient's local environment. In the context of incremental data exchanges, this further implies that a referencein later Message to some data item can rely on that reference being correctly understood. For example, if the first Message sends the details of a Task_method, then the later Message need only reference that Task_method, and need not resend the details.

Message

A Message is a collection of information, brought together by an originator (the message definer) to send to some other system for some particular purpose, generally the fulfillment of a process. It is an historical record, intended to be sent (using an Envelope) and in consequence, is not versioned. The same Message can be sent several times using different Envelopes. Once it has been sent once, it may not be further changed. However it should not be used to simply record information and remain unsent, since that is to confuse its functions with other entities such as some usages of Document or with Observation.

In the context of a PLCS DEX, a Message is part of the DEX data set, and its Content_items provide references to each occurrence of the information that is the focus of the DEX. For example, for task_set, each Content_item is a task specification, and a single exchange may contain many such specifications. If the DEX uses a part 21 file, then the Message will appear as part of the file, unlike the Envelope. A useful analogy for Message is e-mail. An e-mail comes in four parts:

Message also comes with Message_relationship, which allows a range of relations such as [Message_reply]

Error RDL1: The class Message_reply does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
or [Message_supercedes]

Error RDL1: The class Message_supercedes does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
. Unlike e-mail, it also may have a State_predicted_to_observed, which can be used to track the lifecycle of the Message. Since Message states are part of the business processes of the users of PLCS, no state model is defined in this usage guidance.

The Message should be classified with a subclass drawn from each of the following:

A simple example of a Message is shown in figure 4 below - the use of Content_item is discussed in the following section.

Security_classification, Approval, Contract and Information_right are optional, and requirements on their use depends on any exchange agreement. Each characterization applies to the Message as a whole, rather than to a particular content data item. The use of Partial_document_assignment is restricted to supporting information about the Message and may not be used to send content product or product support information.

A Date_time may be assigned to the Message in the roles of [Date_message_composed]

Error RDL1: The class Date_message_composed does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
, and "Date message data frozen" (urn:plcs:rdl:std:Date message data frozen) The former is the nominal date when the Message was composed, that is, the date when the first content data was added. The latter has the specific meaning that the attributes of the Message and any of the data in the Content_items take the values that they had in the originating system at the time of freezing. That is, the values in the Message were up-to-date at that point in time, and the contents of the Message have not altered since that time (although the values may have changed in the originating system). It is impossible for a Message to be frozen after any Envelope that sends it. This class may not be used if the contents of the Message have been collected over an extended period.

A Message may have one or more Organization or Person_in_organization assigned, with the Organization_or_person_in_organization_assignment being classified by the role the person or organization plays. This has the role of[Message_sender]

Error RDL1: The class Message_sender does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
only if the sender is different from the Message definer, for example, when the offical sender is a manger, although the content is prepared by one of their staff. An assignment in the role of[Intended_recipient]

Error RDL1: The class Intended_recipient does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
is used to define an intended target of the Message and is expected to act on it, while the role of [Intended_copied_to]

Error RDL1: The class Intended_copied_to does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
is used when the recipient is sent the information for reference only.

The attribute, message_type is in effect a classification of Message and is set to \IGNORE".

Whenever a Message is part of a DEX data set, the Message is classified as described below in the section on Message And DEXs

Content_item

The reference mechanism for Content_item is indirect, since otherwise STEP mapping rules would require a mapping for every entity in the application protocol. For many reasons, this is impractical. This poses two questions: how does the mechanism work? and to what exactly does it refer? Note, the same concept of "escape" mechanism is also used in Observation.

In a PLCS DEX data set, a Content_item item_identifier points to the head entity of one occurrence of the thing that the DEX specifies. For example, if the DEX specifies how to send a Task_method, then a item_identifier points to the Task_method_version, which therefore links to the complete specification of the task. It is required that each DEX specify its head entity to be referenced by item_identifier

To enable the item_identifier reference to be meaningful, Content_item comes with two additional attributes: item_type, and access_comment. item_type describes what sort of thing is being referenced, such as "PLCS-ARM:Product". In PLCS, item_type should always be of the form either PLCS-ARM:[entity_name] where [entity_name] is the name of the entity as it appears in the ARM or PLCS-AIM:[entity-name], where [entity] is the name of the entity as it appears in the AIM. The short name form may be substituted for the long name.

access_comment provides information to the system interpreting the Message on how to read the data, such as "STEP Part 21 File:Line". The mechanism used is implementation dependent.

In a STEP part 21 file, the default access comment should read "STEP Part 21 File:Line", and the item_identifier should be the line number including the "#" prefix. Note, the difference between a line number as a part 21 reference and the item_identifier line number is that, in the latter case, the line number is a quoted string.

Similarly, in an XML file, the item_identifier will have the same form as the XML cross-reference, except it will appear as a quoted string. The form of this cross-reference will be determined by the binding used. The default binding is specified though ISO 10303-28, using the PLCS configuration rules.

The mechanism to be used in a database will be implementation dependent. For example, in an ARM-based implmentation, the system could treat the item_identifier as an ordinary entity reference, as if the item_identifier were a select entity.

Message is not limited simply to providing a means of referencing EXPRESS entities. It can be used as a means of referencing files, images, and so on, although this usage is beyond the scope of this capability.

Message and DEX

In PLCS, the primary "unit of exchange" is the DEX. Each DEX specifies the data needed to enact a particular interprocess flows in the PLCS AAM. Only a single DEX specification is allowed to be instantiated as part of a Message in a DEX data set, but it can be instantiated multiple times. (Note: the term PLCS DEX is used of the specification, the term DEX data set used to refer to an instantiation of that specification.) In addition to the classifications identified above, a Message should be classified to indicate its content, with a single classification from each of the following three superclasses:

At the time of writing, AP239-version has a single subclass AP239-2005 for the initial publication.

[DEX_used]

Error RDL1: The class DEX_used does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
has the following subclasses:

Each of these classes has a further subclass, indicating the version of the DEX used.

[PLCS_environment]

Error RDL1: The class PLCS_environment does not exist in RDL at URI urn:plcs:rdl:std. Check the dexlib/data/refdata/rdl_index.xml
is a root classification intended to be extended by the users, to indicate which exchange agreement the DEX data set is covered by. The exchange agreement covers issues such as allowed string lengths, data content rules, cardinality constraints and the reference data library to be used, and consequently, it determines any translator settings used in the unpacking of the data. The root class PLCS-environment must be extended to identify the particular environment. Since each extension class will be part of an exchange agreement, to minimise the chance of any clash between PLCS-environment subclasses, the subclass shall take the form PLCS-environment-[date]-[product]-[lead organization] or PLCS-environment-[date]-[product]-[lead organization]-[secondary-id] where:

Where a secondary identifier is used, the PLCS-environment-[date]-[product]-[lead organization]-[secondary-id] should be a subclass of PLCS-environment-[date]-[product]-[lead organization]. Since the function of the PLCS-environment subclass name is solely to avoid confusion between two different exchange environments, strong guidance on the form of the subfields is not required.

Capability templates

The following sections define a set of templates for the capability, where a template is a specification of a set of entities that need to be instantiated to represent a given set of information.

NOTE An explanation of a template and the associated instantiation path is provided in the Template overview section.

This template describes the representation and identification of a message and the relationships between a message and its contents.

The following input parameters are defined for this template:

The following reference parameters are defined for this template:

Content_item should never be instantiated; only Content_item_selected should be instantiated. In other words, Content_item should be used (in effect) as though it were an abstract supertype.

The instantiation path shown below specifies the entities that are to be instantiated by the template.

A description of templates and the syntax for the instantiation path is provided in the Reading Capability Templates help section.

Message

-- Mark the Message entity as
-- referable when this template is used by binding it to the reference
-- parameter message
%^message = Message%
Message.id = '/IGNORE'
Message.message_type = '/IGNORE'
Message.purpose = '/IGNORE'
Message.contains -> Content_item_selected

-- Mark the Content_item_selected entity as
-- referable when this template is used by binding it to the reference
-- parameter content_item
%^content_item = Content_item_selected%
Content_item_selected.contents -> @content
Content_item_selected.item_identifier = '/IGNORE'
Content_item_selected.item_type = '/IGNORE'
Content_item_selected.access_comment = '/IGNORE'

-- assign ID to message
/assigning_identification(
    id=@rep_msg_id,
    id_class_name=@rep_msg_id_class_name,
    id_ecl_id=@rep_msg_id_ecl_id,
    org_id=@rep_msg_id_owner,
    org_id_class_name=@rep_msg_id_owner_class_name,
    org_id_ecl_id=@rep_msg_id_owner_ecl_id,
    items=^message)/

-- provide the version of the AP
/assigning_reference_data(
    items=^message,
    class_name=@dex_id_class_name,
    ecl_id=@dex_id_ecl_id)/

-- provide the version of the AP
/assigning_reference_data(
    items=^message,
    class_name=@ap239_id_class_name,
    ecl_id=@ap239_id_ecl_id)/

-- assigning an actual date of the message - the date the message was created
/assigning_time(
    date_class_name=@date_class_name,
    date_ecl_id=@date_ecl_id,
    year=@year,
    month=@month,
    day=@day,
    hour=@hour,
    minute=@minute,
    second=@second,
    sense=@sense,
    hour_offset=@hour_offset,
    minute_offset=@minute_offset,
    items= ^message)/

The following entities are instantiated with attributes as specified:

Entity in path	Value	Inherited from
Message.id	'/IGNORE'	—
Message.message_type	'/IGNORE'	—
Message.purpose	'/IGNORE'	—
Content_item_selected.item_identifier	'/IGNORE'	Content_item.item_identifier
Content_item_selected.item_type	'/IGNORE'	Content_item.item_type
Content_item_selected.access_comment	'/IGNORE'	Content_item.access_comment

Note that the assigning_organization or assigning_person_in_organization template must be used with the representing_message template to indicate both the sender and the receiver of the message as indicated below:

/assigning_organization(org_id='Parts R Us Ltd', org_id_class_name='Organization_name', org_id_ecl_id='urn:plcs:rdl:std', org_assign_class_name='Sender_of', org_assign_ecl_id='http://www.plcs.org', items='#124')/

/assigning_person_in_organization(items='#124', last_name='Berry', first_name='Janet', middle_names='', prefix_titles='', suffix_titles='', person_role_class_name='Receiver_of', person_role_ecl_id='urn:plcs:rdl:std', org_id='Express Delivery Inc', org_id_class_name='Organization_name', org_id_ecl_id='urn:plcs:rdl:std')/

Note that the assigning_reference_data, assigning_time and assigning_identification templates are used in the diagram. Namely:

/assigning_reference_data(items='#124', class_name='DEX_message_aviation_maintenance_v1', ecl_id='urn:plcs:rdl:std')/

/assigning_reference_data(items='#124', class_name='AP239_ed1_tc1_message', ecl_id='urn:plcs:rdl:std')/

/assigning_identification(items='#124', id='CM1234', id_class_name='Message_identiification_code', id_ecl_id='urn:plcs:rdl:std', org_id='Express Delivery Inc', org_id_class_name='Organization_name', org_id_ecl_id='urn:plcs:rdl:std')/

/assigning_time(items='#124', date_class_name='Date_message_sent', date_ecl_id='urn:plcs:rdl:std', year='2007', month='6', day='13', hour='11', minute='23', second='54', sense='.EXACT.', hour_offset='0', minute_offset='0')/

The following section details how the representing_message template can be optionally characterized by assigning other constructs to it. These are characterizations commonly applied to the template. The ISO 10303-239 EXPRESS model may enable other assignments to the entities instantiated by the template.