Annex C Extensions - STARIONGROUP/COMET-SDK-Community-Edition GitHub Wiki

Introduction

CDP4-COMET is compliant to ECSS-E-TM-10-25 Annex A, Annex B and Annex C. The CDP4-COMET provides more capabilities than a pure ECSS-E-TM-10-25 through extensions of Annex A and Annex C. The Annex C extensions are explained here. The following Annex C extensions can be identified:

JSON REST API - C2
- HTTP Headers
- Time Travel
- Revisions
- Copy Operation
- Restore and Reseed
MessagePack Respnse - C2
JSON Exchange File Format - C3

These extensions have been implemented on the CDP4-COMET Web Services and the CDP4ServicesDal-Overview.

JSON REST API

HTTP Headers

The CDP4-COMET Web Services are able to include or exclude the [CDP4 Data Model]] classes in the response of a GET or POST request. HTTTP headers are used to communicate to the CDP4-COMET Web Services that the client supports CDP4-COMET concepts and what [version is supported. The Accept-CDP HTTP header is used to let the CDP4-COMET Web Services know that CDP4-COMET extensions are accepted by the client that is making the GET or POST requests.

A response from the CDP4-COMET Web Services will always contain the following HTTP Headers:

CDP4-Server: The header that is used to communicate the version of the server that is being used
CDP4-Common: The header that specifies the version of the CDP4Common library that is being used
Content-Type: The header that specifies the ECCS-E-TM-10-25 protocol and it's version. The CDP4-COMET Web Services return application/json; ecss-e-tm-10-25; version=1.0.0 while a pure E-TM-10-25 implementation returns application/json.

The CDP4-COMET WebServices (as of Version 8.0.0) and the CDP4-COMET-SDK (as of version 24.0.0) support MessagePack serialization. The WebServices supports the following Accept headers:

application/json: The response is a ECSS-E-TM-10-25 JSON response that is implemeted in the Json Serializer library
application/msgpack: The response is a CDP4-COMET MessagePack response that is implemeted in the MessagePack Serializer library. Even though the content is encoded in MessagePack, it is 100% as the JSON content, albeit that the structure is different. In case both are provided, the response will be returned as MessagePack.

Time Travel

The revision query-parameter is used to request the objects that have a revision equal to or higher than a certain revision number. This query-parameter is used to requests only those objects that have been added or updated after a specific revision; this provides support in a polling strategy to only retrieve the new and updated objects.

The timeTravel query parameter on the other hand is used to request a specific revision of an object, including its contained object graph.

parameter	value	description	Combination
timeTravel	Valid values are a revision number as an integer or a timestamp in the ISO 8601 format.	Returns the set of all objects contained by the object specified in the URI, that have a revisionNumber that is equal or lower than the given value. When a timestamp is used, this is translated to the revisionNumber that was created at the provided timestamp, or the first revision that is found with a timestamp smaller (earlier) than the provided timestamp.	This query-parameter can be combined with the extent query parameter to request a single object as well as it’s containment tree. This query-parameter cannot be combined with the revision query-parameter. This query-parameter can be combined with the includeReferenceData query-parameter. The returned reference data is that reference data that was valid for the requested timeTravel revision or timestamp value.

Revisions

The revisionFrom and revisionTo query parametsers are used to request selected revisions of an object.

parameter	value	description	Combination
revisionFrom	Valid values are a revision number as an integer or a timestamp in the ISO 8601 format.	Specifies that all revisions of an object are requested starting at the specified lower revision. If no revisionTo query-parameter is specified the range that is requested includes all revisions until the most recent revision.	This query parameter can only be combined with the revisionTo query-parameter
revisionTo	Valid values are a revision number as an integer or a timestamp in the ISO 8601 format.	Specifies that all revisions of an object are requested until the specified upper revision. If no revisionFrom query-parameter is specified the range that is requested starts a revision 0.	This query parameter can only be combined with the revisionFrom query-parameter.

Copy

Annex C.2 prescribes the POST HTTP verb to create, update and delete items. The POST request has the following format, specified in Annex C - POST request. A POST message is a JSON object that contains three properties also called parts; a part that contains those objects that need to be created, a part that contains the objects that need to be updated and those objects that need to be deleted.

{
  "_create": [],
  "_update": [],
  "_delete": []
}

A copy part is added to the protocol to request the data-source, such as the CDP4-COMET Web Services, to copy Things between a source and a target Engineering Model. This increases performance and allows copy operations which would not be possible when constructed solely on the basis of add and subsequent update operations. Furthermore, it makes sure that a copy is complete and is not incomplete because a client may lag behind with respect to data present on the server.

Here after is defined in more details the copy operation.

{
  "_delete", [],
  "_update": [],
  "_create": [],
  "_copy": [
    {
      "source": {
        "thing": {
          "iid": "fe9295c5-af99-494e-86ff-e715837806ae",
          "classKind": "ElementDefinition" 
        },
        "topContainer": {
          "iid": "9ec982e4-ef72-4953-aa85-b158a95d8d56",
          "classKind": "EngineeringModel"
        },
        "iterationId": "e163c5ad-f32b-4387-b805-f4b34600bc2c"
      },
      "target": {
        "container": {
	  "iid": "e163c5ad-f32b-4387-b805-f4b34600bc2c",
	  "classKind": "Iteration"
	},
	"topContainer": {
	  "iid": "9ec982e4-ef72-4953-aa85-b158a95d8d56",
	  "classKind": "EngineeringModel"
	},
	"iterationId": "e163c5ad-f32b-4387-b805-f4b34600bc2c"	
      },
      "options": {
	"copyKind": "Deep",
	"keepValues": true,
	"keepOwner": true
      },
      "activeOwner" : "0e92edde-fdff-41db-9b1d-f2e484f12535"
    }    
  ]
}

Source: The source specifies the Thing that is to be copied. The source Thing is defined by the Thing's ClassKind and unique identifier, along with its top-container information and optionnally the Iteration identifier if the data is contained by an Iteration.
Target: The target specifies the target container in which the Thing will be copied. The target is defined by the target container ClassKind and unique identifier along with its top-container information and optionnally the Iteration identifier if the data is contained by an Iteration. The target may be the same as the source, which effectively means that a Thing is copied inside the Model it already resides.
Options
- copyKind: (Deep|Shallow) specifies whether the whole containment hierarchy shall be copied in the target (Deep), or just the object without its containment (Shallow) tree
- keepValues?: (true, false) specifies whether the values shall be kept if Parameter, ParameterOverride or ParameterSubscription are copied
- keepOwner?: (true|false) specifies whether the owner are kept when applicable. Active owner: This option specifies the identifier of the domain responsible for the operation and is used if ownership of copied object are changed when applicable

NOTE: Option and State-dependency of parameters are only kept when copying an Thing in the same Iteration. They are otherwise dropped. Categories shall be discarded during the copy operation if the category are not available in the target Engineering Model.

Restore and Reseed

In order to support integration tests defined in the ECSS-E-TM-10-25 Annex C - Integration test suite 2 routes have been added to Annex C.2 with the following purpose:

An "upload an Annex C.3 compliant seed file" service. The seed file forms the basis for the tests and is the known state of the data set on which the tests have been based. By uploading such a seed file the complete data set is reset to the state described in the seed file.
A "restore" service that restores the dataset on the service to the last seeded file.

Method	Request	Notes
POST --form	http[s]://cdp4services-public.cdp4.org/Data/Exchange	Upload an ECSS-E-TM-10-25A Annex C.3 exchange archive that will seed the datastore. This feature Can be disabled in CDP4-COMET Server configuration file.
POST	http[s]://cdp4services-public.cdp4.org/Data/Restore	restore/reseed of the datastore (e.g. for rollback or testing) to the previously provided ECSS-E-TM-10-25A Annex C.3 exchange archive. This feature Can be disabled in CDP4-COMET Server configuration file.

JSON Exchange File Format

The CDP4-COMET does not provide any JSON Exchange File Format extensions at this time.

CherryPick

A Cherry Picking feature has been implemented. This feature enable to query a subset of an Iteration, based on some ClassKind and Category filters.

To implement this feature, 3 new QueryParameters have been added :

cherryPick : A boolean (false/true) that is used to enable the feature
classkind : A collection of ClassKind names, in UpperCase, that is requested to retrieve
category: A collection of Category ShortGuid (A UUID that have been shorten) that Thing have to be Categorized by.

This feature is only enable when a Get request is done against an Iteration. Here is an example of a valid url for the CherryPick feature :

http[s]://cdp4services-public.cdp4.org/EngineeringModel/9ec982e4-ef72-4953-aa85-b158a95d8d56/iteration/e163c5ad-f32b-4387-b805-f4b34600bc2c?classkind=[PARAMETER;ELEMENTDEFINITION]&category=[3QV4ayC1TkObkCdSSmdvow;GZsFz1wjvkiHo5qJQsjj4A]&cherryPick=true

Remarks : The Response will contains all Things that match the ClassKind and Category filter with all container of those Things