CCOM BOD Structure – MIMOSA Temp

CCOM BODs are currently in draft and are only available to MIMOSA members.

The BOD example currently references CCOM 3.2.3 and will be updated to CCOM 4.0.0 in the near future.

While CCOM provides an object model and canonical XML representation of that model, the XML representation is often unsuitable for more than just basic data integration. The Open Applications Group Integration Specification (OAGIS) Business Object Document (BOD) message structure is used to provide additional message concepts that encapsulate a MIMOSA CCOM payload. Specifically, OAGIS Platform Specification 1.2.1 is referenced by CCOM 4.0.

BODs indicate both behavior and structure for messages and the major components of a BOD are depicted below.

The major components of the BOD are:

The Application Area is for transactional meta-data, such as identifiers associated with the sender, a creation time stamp, and a unique identifier for the BOD.
The Data Area contains a Verb (in other words, the operation) as well as a Noun (the business object of that operation).
The Verb can indicate either what operation to perform (for example, Get) or a response to an operation (for example, Show).
The Noun instance contains the data representing the business object that is being managed. The Nouns in this case, are composed of MIMOSA CCOM data structures.

Example

The following is a trivial BOD example intended to help associate the concepts from the prior section to the XML syntax used by BODs.

<?xml version="1.0" encoding="utf-8"?>
<SyncAssetInstall
  xmlns:oa="http://www.openapplications.org/oagis/9"
  xmlns:ccom="http://www.mimosa.org/osa-eai/v3-2-3/xml/CCOM-ML"
  xmlns="http://www.mimosa.org/osa-eai/v3-2-3/xml/CCOM-ML/BOD"
  releaseID="1.0">
  <oa:ApplicationArea>
    <oa:Sender>
      <oa:LogicalID>ef7e08db-c377-4f0b-8437-12c90272cc35</oa:LogicalID>
    </oa:Sender>
    <oa:CreationDateTime>2010-03-30T13:21:00Z</oa:CreationDateTime>
    <oa:BODID>a28c4811-0a62-4eaa-8ab2-6372d744ed92</oa:BODID>
  </oa:ApplicationArea>
  <DataArea>
    <oa:Sync>
      <oa:ActionCriteria>
        <oa:ActionExpression actionCode="Add">
          /SyncAssetInstall/DataArea/AssetInstall
        </oa:ActionExpression>
      </oa:ActionCriteria>
    </oa:Sync>
    <AssetInstall versionID="1.0">
      <Asset>
        <ccom:GUID>df3cb180-e410-11de-8a39-0800200c9a66</ccom:GUID>
        <ccom:Tag>3Z84G32AA0-4</ccom:Tag>
      </Asset>
      <Segment>
        <ccom:GUID>5f331ace-da04-447c-b371-30dd01e285c3</ccom:GUID>
        <ccom:Tag>J-9005B Motor</ccom:Tag>
      </Segment>
      <AssetOnSegmentEvent>
        <ccom:GUID>76238289-57a9-4ef5-888f-ea131b46dd60</ccom:GUID>
        <ccom:Type>
          <ccom:GUID>ecc99353-412b-4995-bd71-1cbc6fc16c7c</ccom:GUID>
          <!-- Installation of Asset on Segment -->
        </ccom:Type>
        <ccom:End>2010-03-30T13:21:00Z</ccom:End>
        <ccom:Asset>
          <ccom:GUID>df3cb180-e410-11de-8a39-0800200c9a66</ccom:GUID>
          <!-- 3Z84G32AA0-4 -->
        </ccom:Asset>
        <ccom:Segment>
          <ccom:GUID>5f331ace-da04-447c-b371-30dd01e285c3</ccom:GUID>
          <!-- J-9005B Motor -->
        </ccom:Segment>
      </AssetOnSegmentEvent>
    </AssetInstall>
  </DataArea>
</SyncAssetInstall>

Note:

Components with the oa: prefix are from the OAGIS namespace.
The BOD has a type of SyncAssetInstall, which following the OAGIS guidelines, is the concatenation of the Verb and Noun.
The ApplicationArea contains a unique sender identifier (oa:LogicalID), a message creation timestamp (oa:CreationDateTime) and a unique message identifier (oa:BODID).
Within the DataArea, there is a Sync Verb and an AssetInstall Noun instance.
Sync is an action verb type, and the ActionExpression sets the scope of what is to be managed.
An ActionCode of Add and the expression (in this case, using the default XPath expression language) comprise an instruction to be performed on the noun, in this case the creation/addition AssetInstall instance.
The Noun is a MIMOSA CCOM AssetInstall instance.

BOD Attributes

The attributes of a BOD are:

releaseID	Identifies the version of the BOD platform (e.g. 1.2.1) to indicate the BOD message structure to consuming applications. This is mandatory at the schema level.
versionID	Identifies the version of the BOD itself (e.g. 1.0). While not mandatory at the schema level, this is mandatory for MIMOSA CCOM BODs.
systemEnvironmentCode	Can be used to identify in which environment the BOD is being sent; for example, Test or Production.
languageCode	Indicates the language of the contents of the BOD. It is possible to override the BOD level languageCode for fields that may need to carry multi-lingual information.

Application Area Elements

The elements within an ApplicationArea are:

Sender	Identifies characteristics and control identifiers that relate to the application that created the BOD. It can indicate the logical location of the application and/or database server, the application, and the task that was processing to create the BOD. ConfirmationCodes are also supported for error reporting.
Receiver	Depreciated by OAGIS and not used by MIMOSA.
CreationDateTime	The UTC date time stamp that the given instance of the BOD was created. This date must not be modified during the life of the BOD.
Signature	Digital signature used for message signing. While the signing mechanism is project specific and not standardized by MIMOSA, the use of message signatures is highly recommended.
BODID	Universally Unique Identifier (UUID) that identifies the BOD.
UserArea	An extensibility element to allow additional data to be added to the ApplicationArea. Its use is project specific and not standardized by MIMOSA.

Verbs

The verb types that are supported by MIMOSA align with the basic publish-subscribe and request-response messaging models used by the OpenO&M ws-ISBM and include:

Get (for requests)
Show (for responses)
Sync (for publications)
Confirm (for confirmation)

Get Verb

The Get verb is to communicate a request for an existing piece of information to be returned. The response to this request is the Show verb. The Get is typically used to retrieve a single piece of information by using an ID for the related element. However, Get may also support certain reporting needs by enabling the retrieval of a range of documents matching a given filter.

Attributes

The following supported Get verb attributes can be used to request data to be returned in batches, where the batches are associated to a record set by a reference identifier. A default value is specified for some attributes if it is omitted.

uniqueIndicator	A true value indicates that duplicates should be filtered out. Default: true
maxItems	The maximum number of records that should be returned in a record set batch. Default: Noun’s maxOccurs attribute
recordSetSaveIndicator	A true value indicates that receiver should save the record set snapshot for later reference. The corresponding Show response will have a record set reference identifier. Default: false
recordSetStartNumber	The record number identifying the first record that should be returned in the Show response. Default: 1
recordSetReferenceID	Unique identifier to specify a given record set. It is generated by the producer of the Show response as a result of a Get request that has indicated to save the record set snapshot. Default: null

Expression

The Expression element is project specific and not standardized by MIMOSA.

Show Verb

The Show verb is used when sending the information about a specific instance of a business document or entity. It is used in message instances returning the results of “read” instructions sent in a message instance using the Get verb.

Attributes

The following supported Show verb attributes can be used to respond to a Get batch request, where the batches are associated to a record set by a reference identifier. A default value is specified for some attributes if it is omitted.

recordSetStartNumber	The record number identifying the first record returned in the Show response for the given record set. Should match the Get request recordSetStartNumber attribute. Default: 1
recordSetCount	Number of records in the record set batch. Should match the Get request maxItems attribute.
recordSetTotal	Number of records in the record set. Should match recordSetCount if the Get request maxItems attribute is larger.
recordSetCompleteIndicator	True if this is the last batch in the record set. Default: true
recordSetReferenceID	Unique identifier for a given record set. It is generated by the producer of the Show response as a result of a Get request that has indicated to save the record set snapshot. Default: null

Original Application Area

This is a copy of the ApplicationArea for the original Get request that was processed. It is used as reference information and can be used for request-response message correlation. If the BODs are used with the OpenO&M ws-ISBM, as the ws-ISBM also provides request-response message correlation functionality, a BOD’s original application area may be omitted.

Response Criteria

The ResponseCriteria element is project specific and not standardized by MIMOSA.

Sync

The Sync verb is used when the owner of the data is passing or publishing that information or change in information to other software components. This is to be used when the receiver of the Sync BOD does not own the data. This verb is commonly used when mass changes are necessary or when a publish and subscribe mechanism is used in the integration architecture. The purposes of this verb include application integrity and ease of data entry for the business user by enabling a single point of input.

Attributes

The following supported Sync verb attributes can be used to publish data in batches, where the batches are associated to a record set by a reference identifier. A default value is specified for some attributes if it is omitted.

recordSetStartNumber	The record number identifying the first record returned for the given record set. Default: 1
recordSetCount	Number of records in the record set batch.
recordSetTotal	Number of records in the record set.
recordSetCompleteIndicator	True if this is the last batch in the record set. Default: true
recordSetReferenceID	Unique identifier for a given record set. Default: null

Action Criteria

The ActionCriteria associated with the Sync verb is supported, which provides the ability to apply fine-grained expressions on how to interpret noun elements.

An ActionExpression must contain an XPath 1.0 expression that identifies the entire noun or a selected element in the noun, and an actionCode that applies to the evaluation of the XPath expression and its child nodes. As only XPath 1.0 is supported, the expressionLanguage attribute can either be set to XPath 1.0 or be omitted.

actionCodes are dependent on the noun payload itself: a snapshot approach, where the full entity is sent, may only use an actionCode of Replace. A incremental approach, where only the parts of an entity have been created, updated or deleted are sent, may only use an actionCode of Add, Change or Delete.

A snapshot approach is generally considered to be simpler to implement than the incremental approach; however, messages are larger in size thereby requiring a longer processing time than those based on the incremental approach. Both approaches can also be used within the same message.

Where there are multiple ActionExpressions, each is processed in specified order; however, this complexity may warrant using a simpler snapshot approach instead.

An example of the usage for each of the actionCodes is shown in the following example:

<DataArea>
  <oa:Sync>
    <oa:ActionCriteria>
      <oa:ActionExpression actionCode="Add">
        /SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:LastEdited
      </oa:ActionExpression>
      <oa:ActionExpression actionCode="Change">
        /SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:Type
      </oa:ActionExpression>
      <oa:ActionExpression actionCode="Delete">
        /SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:Name
      </oa:ActionExpression>
      <oa:ActionExpression actionCode="Replace">
        /SyncSegmentDefinition/DataArea/SegmentDefinition/
        Segment/ccom:ValidNetwork
      </oa:ActionExpression>
    </oa:ActionCriteria>
  </oa:Sync>
  <SegmentDefinition versionID="1.0">
    <Segment>
      <ccom:GUID>5f331ace-da04-447c-b371-30dd01e285c3</ccom:GUID>
      <ccom:Tag>J-9005B Motor</ccom:Tag>
      <ccom:Name>C3/C4 Splitter Reflux Pump Motor</ccom:Name>
      <ccom:LastEdited>2012-01-01T00:00:00</ccom:LastEdited>
      <ccom:ValidNetwork>
        <ccom:GUID>0ad76534-2325-4a58-bce6-1558a5f6a41e</ccom:GUID>
        <ccom:Network xsi:type="DataSheet">
          <ccom:GUID>e3c200b5-99a0-4387-878a-be551894596a</ccom:GUID>
          <ccom:Tag>J-9005B Motor Requirements Data Sheet</ccom:Tag>
          <ccom:Name>J-9005B Motor Requirements Data Sheet</ccom:Name>
          ...
        </ccom:Network>
      </ccom:ValidNetwork>
      <ccom:Type>
        <ccom:GUID>5f3f1c9c-36f8-49df-9d19-aa12700d4c23</ccom:GUID>
        <ccom:Tag>Motor, AC, Induction</ccom:Tag>
      </ccom:Type>
    </Segment>
  </SegmentDefinition>
</DataArea>

Note: The contents of the DataSheet has been omitted for brevity.

The four ActionExpressions can be interpreted as:

actionCode	ActionExpression	Interpretation
Add	/SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:LastEdited	Add the LastEdited property to the Segment
Change	/SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:Type	Change the Type property of the Segment to the specified type
Delete	/SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:Name	Delete the Name property of the Segment, regardless of its contents
Replace	/SyncSegmentDefinition/DataArea/SegmentDefinition/Segment/ccom:ValidNetwork	Replace the ValidNetwork property of the Segment with the specified contents, even if it previously contained multiple values

A receiver may also interpret a Change as an Add if the property does not have an existing value. However, it is typically a safer approach to request (Get) the entity in question from the sender to receive the full definition.

A ChangeStatus may also be supplied with an ActionCriteria to indicate the reason for the change, although its use is project specific and not standardized by MIMOSA.