Help:- Template overview

When specifying a DEX, it is necessary to define the scope and agree the precise content of the exchange. This is typically achieved by defining a set of business objects that use business level terms to precisely define the content. It is then necessary to specify how the PLCS PSM is used to represent those business objects. In other words, to show how the business objects are "mapped" to the PLCS PSM. In practice, the scope of DEXs will overlap, with similar business objects repeatedly using the same PLCS PSM constructs.

Templates are the mechanism that has been developed to define the business objects and specify their mapping to the PLCS PSM. A template provides an unambiguous specification of the instantiation of a collection of PLCS PSM blocks and attribute values, and external Reference Data required to represent a particular business object. The aim is to ensure consistent interpretation and re-use. Furthermore, the templates provide usage guidance for the PLCS PSM model. It should be noted that templates can be built up from other templates.

A Template represents a named grouping of PLCS PSM objects that are to be instantiated in order to represent a business object.

The remainder of this section provides a description of templates and their specification.

• Section Information hierarchy describes the information hierarchy implicit in a DEX and the role of a templates in that hierarchy;
• Section Template representation describes how a template is formally represented using SysML;
• Section Template documentation describes how a template is documented in PLCSlib.

Figure 1 shows the mapping of the business objects to the PLCS PSM. The diagram shows a Business Object model, mapped to templates and then to the PLCS PSM model. The business objects are in fact templates in their own right. Their mapping to the PLCS PSM model can be direct or by using pre-existing templates. A number of these pre-existing templates have been defined as part of an OASIS standard and hence part of the OASIS context.

A template represents a business object, and the pattern of PLCS PSM blocks that are to be instantiated by the template. This relationship is illustrated in Figure 2 which shows the Organization template and the set of Blocks that represent the template.

A template is represented at two levels:

• First as a SysML Block. This in effect specifies the business object that is represented by the template. This is described in Section "Template Block".
• The second level is the set of PLCS PSM blocks and other templates that are to be instantiated by the template. This is shown in Figure 2 with the shaded area highlighting the blocks that represent the business object. The set of objects that represent a template are formally specified by a SysML Parametric Diagram. The use of Parametric Diagrams is described in the Section "Template Parametric Diagram".

The business object represented by the template is represented as a SysML Block. This is shown in Figure 3 which shows the SysML Block for the business object is an Organization.

The block shows:

• The name of the Block;
• The public properties of the Block;
• The constraints that apply to the Block;
• The output ports of the Block;

The properties of the template / business object are the attributes of the Block and these are either, Reference, Part or Value properties.

• Reference properties - refer to objects that are not deletion dependent on the template. I.e. objects that may be used by / referenced by other templates. For example, Classification etc. In the case of the Organization, the "idClass" is a reference property of type ClassifedBy - the class referred to by the "idClass" may be classifying other objects, for example other Organizations.
• Part properties - refer to objects that are deletion dependent on the template. These are principally Descriptions. i.e. objects that are only instantiated/used in the context of the template. In the case of the Organization, the "description" is a part property as a Description is an object that is specific to the one Organization for which it is a description.
• Value properties - refer to simple types such as Strings, Booleans and Numbers. In the case of the Organization, the "id" is a value property.

Each property has an associated multiplicity. This indicates how many of the properties are to be set with the Block. The possible multiplicities are

• [1] - the property is mandatory and must be set once;
• [0..1] - the property is optional. It must be set 0 or 1 times;
• [0..*] - the property is optional. There may be more than one value for the property.

The property may have a default set. This references a default instance that has been instantiated. For example, Organization shown in Figure 3 has a property idClass. This is defaulted to the instance classCAGECode shown in Figure 4.

The Block shows the SysML constraints specified as OCL that apply to the Block. In the example, the constraint:

 Organization::allInstance()->isUnique(Sequence{id,idClass})

specifies that there shall be only one Organization within the data set uniquely identified by a combination of the following parameters on the template namely: Organization.id, Organization.idClass.

The Block also shows the output ports of the block. These are described in Section "Parametric Diagram - output ports". These expose the PLCS PSM Blocks instantiated/represented by the template for use in other templates.

A template represents an aggregation or abstraction of a set of Blocks. This aggregation of Blocks or set of objects that represent a template are formally specified by a SysML Parametric Diagram. An example is shown in Figure 5. This shows the SysML Block representing the Organization template and its associated Parametric Diagram.

Each of the Blocks in the diagram represents a property of the template. The block contains the name of the property, the type and multiplicity. E.g. The public property id is shown as id:String[1].

The Public properties, those that are set at the template level, are drawn on left of the diagram. The remainder of the blocks are private properties or constraint blocks. Figure 5 shows the link between the public properties at the template level, showing the template Block diagram, and the public properties at the template Parametric diagram level. If the public property is a reference property, then it is shown in a block with a dashed line border in the parametric diagram. E.g. "idClass".

If there is a default value for the property, then it is shown in the block representing the property. E.g. the public property "idClass" in Figure 5 has a default value set as classCAGECode that specifes a value for the class attribute:

      class = http://docs.oasis-open.org/plcs/plcs-psm-std-rdl#CAGE_code

The private properties represent the Blocks to be instantiated by the template. As with public properties, they are shown as blocks that contain the name of the property, the type and multiplicity. The types are Blocks that are either Blocks from the PLCS PSM or Blocks that are themselves templates. If the Blocks are templates, they are shown in Green. For example Figure 5 shows identification:Identification[1]. This is the private property identification of type Identification with a multiplicity of 1. In other words, one instance of an Identification should be instantiated as part of the representation of the Organization template.

The private properties also show the public properties of the type being instantiated. For example Figure 5 shows the private property identification. This is of type Identification which has the public properties identifier and references. These are shown as blocks internal to the private property.

It should be noted that all the mandatory public properties of the type being instantiated are shown as well as any optional properties that are bound. For example, consider the parametric diagram of the Part template shown in Figure 8. The PLCS PSM Block PartVersion bound to the private property partVersion has an optional public property description and references. Neither are shown as they are optional and have not been set by the template.

The combination of public and private properties therefore represents what has to be instantiated in order to represent the template. The binding between the properties in the parametric diagram properties is represented by lines that show what is bound to what. For example in Figure 5 the private property identification is bound to the identifications public property of the templates private property organization.

Occasionally there is a need to combine a number of properties before binding to a private property. The SySML mechanism employed is to use a constraint block to specify how the properties are combined. For example in Figure 6 the public property references of the private property message is bound to the combination of the classifications and DEXVersion public properties. The combineClasses constraint specifies the combination via an OCL function union (shown below) that allows in the constraint parameter combined to be bound to the references public property.

 combined=classes1->union(classes2, classes3, classes4)

Constraint blocks are show as blue and are declared within a template in the Constraint blocks section if required.

The final construct shown on a parametric diagram are Output Ports. These are used to bind to the Blocks shown on the parametric diagram, hence making them available at the Template level where they can be bound to other blocks.

An example is shown in Figure 7 which shows the parametric diagram for the template Identification. The diagram shows that the Identification has a public property organization of type Organization which is a template. (Hence the block is shown in green). The PLCS PSM Block Organization instantiated by the Organization template is bound to the org Output Port of the Organization template which is in turn bound to the identifierContext property - a public property of the PLCS PSM Block Identification instantiated by the Identification template.

The previous sections have described how the template represents the blocks that are to be instantiated in order to represent it. The sections have also described the multiplicity of the properties. The multiplicity controls the optional instantiation of the block in a template. If an optional public property is set when instantiating a template, then anything that is bound to that property must also be set.

For example, consider the parametric diagram for the Part template shown in Figure 8. The private properties, partVersion and partViewDefinition have a multiplicity of [0..1]. In other words, they are optional. If the public property versionId is set, then the block bound to partVersion, namely PartVersion should be instantiated. In this example, the public property viewDefinitionContent is also optional. So if set, then the block bound to partViewDefinition, namely PartViewDefinition should be instantiated. Because partViewDefinition is bound to partVersion and is not optional must also be instantiated, even when no VersionId is specified.

In summary a template Parametric diagram represents the Blocks that need to be instantiated to represent the template. The parametric diagram is analogous to a visual programming language with the template being analogous to a procedure. The properties are variables of the procedure that are bound to types. The public properties are inputs to the procedure. The private properties are variable local to the procedure. The output ports are return values from the procedure.

As has been described, the Parametric Diagram specifies the PLCS PSM Blocks that are to be instantiated. This section provides an instantiation as XML data. An example of the resulting XML data instantiated to represent the template Organization is shown below. The Parametric Diagram for the template is shown in Figure 9. The XML data is provided in two forms, as an XML file and as XML presented as HTML with links to the definitions of the relevant types.

    <!-- Organization instantiated by private property "organization"  -->
    <Organization id="org0">
      <identifications>
        <Identification>
        <!-- Identification instantiated by private property "identification" -->
          <identifier>
            <!-- Identification String set by public property "id" -->
            OrganizationX
          </identifier>
          <references>
            <ClassifiedByOwlClass xsi:nil="true"ref="cls1"/>
          </references>
        </Identification>
      </identifications>
    </Organization>
      
    <!-- ClassifiedByOwlClass set as default to public property "idClass"  -->
    <ClassifiedByOwlClass id="cls1">
      <class>
        <Uri>
           http://docs.oasis-open.org/plcs/plcs-std-rdl#CAGE_code
        </Uri>
      </class>
    </ClassifiedByOwlClass>  

Each template is documented with the same document structure. The specification comprises a SysML Block that represents the template and an associated Parametric Diagram that defines the templates and PLCS PSM objects instantiated by the template.

The specification comprises the following sections:

• Section "Description" provides a description of the template;
• Section "Template Block" specifies the SysML Block that represents the template;
• Section "Template Properties" specifies the properties, i.e. the Part, Reference and Value properties of the template's SysML Block;
• Section "Template Output Ports" specifies the Output Ports of the template's SysML Block. These bind to the templates and PLCS PSM objects instantiated by the template as described in section "Template Parametric Diagram";
• Section "Template Constraints" specifies the constraints on PLCS PSM objects instantiated by the template;
• Section "Template Parametric" Diagram specifies the templates and PLCS PSM objects instantiated by the template;
• Section "Instantiated blocks" specifies the templates and PLCS PSM objects instantiated by the template and bound to private parts of the template;
• Section "Default instances" species the instances that have been instantiated in the template. These are used to set the default value of blocks.
• Section "Constraint blocks" identifies the constraint blocks that have been specified in the template;
• Section "Example data" provides example XML data sets that have been instantiated in accordance with the template.