CDP 4 User Manual

Create, Update and Delete

POST

The CDP4 Web API makes use of the POST verb to create, update and delete items. As such it is not a pure REST API since the PUT, PATCH and DELETE verbs are not supported. A POST request must be accompanied with a POST message that contains information on what items are created, updated and deleted.

The CDP4 Web API accepts a POST message to the following routes:

http://hostname:port/SiteDirectory/{iid}
http://hostname:port/EngineeringModel/{iid}/iteration/{iid}

It is not possible to send POST messages to any other route, this includes an EngineeringModel route:

http://hostname:port/EngineeringModel/{iid}

Even though an EngineeringModel contains items other than Iterations, to create, update or delete these kinds of Thingss a, POST message must be sent to an Iteration that is contained by the same EngineeringModel.

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. The CDP4 WebServices will execute the POST message as a transaction and if an operation on one of the instances fails, the whole operation or POST fails.

The post message has the following format:

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

Create and Update

The _create and _update properties of the transaction object (the POST message) are used to create new items and update existing items. Except for the TopContainers SiteDirectory and EngineeringModel, all the classes in the CDP4 data-model are contained by another class. For instance a EmailAddress is contained by a Person. Every container has knowledge of those objects that it contains through the containment properties (composite aggregation), the contained items does not have knowledge of it's container. The result of this is that the creation of a new object also means an update on it's container. The POST message will contain the new object in the _create part, and an update to the containment property of it's container in either the _update part or the _create part. The object that is to be created must be complete, all the properties that are mandatory need to be included in the object.

Objects that are to be updated may be incomplete, only the properties of the object that are updated must be included in the _update part as well as the unique id and the classKind properties. The properties may be scalar or compound, where compound properties may be ordered or unordered. When a scalar property is updated the value of that property is replaced. When an unordered compound property is specified, the items in the collection are added to the object in the CDP4 WebServices, provided that objects with those unique id's are also present in the _create part. If there are no contained objects in the _create part, the intention is to move the objects with those unique id's to the specified object, provided they exist.

The order of items in an ordered compound property is specified as a JSON object that has two properties: a key and a value. The key property is denoted with a k and the value property is denoted with a v. When the k and v properties are present in an object contained in the _update part, the key and value are added to the object in the CDP4 WebServices.

{
  "k": "some key",
  "v": "some value"
}

The order of the items in an ordered compound property may be changed. This is achieved by adding an m property to the ordered item. The value of the k property is updated with the value of the m property in the CDP4 WebServices. The v property must specified as well to assert that the item already exists in the ordered collection.

{
  "k": "original key",
  "m": "new key",
  "v": "existing value"
}

Delete

The _delete property of the transaction object in the POST message is used to delete Things from the CDP4 WebServices. Both complete objects can be deleted or items can be removed from a compound property.

A complete object can be deleted by specifying only it's unique id iid and classKind property. The following example deletes the complete Person object.

{
  "_delete", [
    {
      "iid": "77791b12-4c2c-4499-93fa-869df3692d22",
      "classKind": "Person"
    }
  ],
  "_update": [],
  "_create": []
}

When an object with an unordered compound property is specified in the _delete part, the items in the specified property are deleted from that property in the CDP4 WebServices. The following example deletes the UserPrefence object with unique id equal to 2999e725-9b19-46ec-85bf-e8d22914bad4 from the specified Person object.

{
  "_delete", [
    {
      "iid": "77791b12-4c2c-4499-93fa-869df3692d22",
      "classKind": "Person",
      "userPreference": "2999e725-9b19-46ec-85bf-e8d22914bad4"
    }
  ],
  "_update": [],
  "_create": []
}

When an object with an ordered compound property is specified in the _delete part, the items with the specified sort key(s) are deleted from the ordered compound property. Both the k and v property are specified, the v property is used to verify that the items exists for the specified k value in the ordered compound property. The following example deletes the ruleVerification object with sort-key 12345 and unique id b198ce8e-24c3-409b-ac6b-e0351de51f66 from the RuleVerificationList object:

{
  "_delete", [
    {
      "iid": "98d0c9ee-a98d-4ff0-b9b1-df8eab3a6c2f",
      "classKind": "RuleVerificationList",
      "ruleVerification": [
        { 
          "k": "12345",
          "v", "b198ce8e-24c3-409b-ac6b-e0351de51f66"
        }
      ]
    }
  ],
  "_update": [],
  "_create": []
}

Side Effects

Instances of particular classes can only be created and deleted by the CDP4 WebServices and not by an application that is using the CDP4 Web API. The creation these classes occurs as a side-effect of a create, update and/or delete of other classes. The following sections specify these side-effects.

EngineeringModelSetup

It is forbidden to include an EngineeringModel in the _create or _delete part of a POST message. An EngineeringModel is created as a side-effect of a creation an EngineeringModelSetup.

When an EngineeringModelSetup is created the CDP4 WebServices will:

A Person that does not have a default DomainOfExpertise set may not create an EngineeringModelSetup

When an EngineeringModelSetup is deleted the referenced EngineeringModel is deleted as well.

Instantiate from Source model

An EngineeringModelSetup can be instantiated from a source model by:

Depending on the EngineeringModelKindof the new and referenced source model respectively different instantiation modes exist:

EngineerinmodelSetup instantiation from source logic pseudo code:

newKind = Kind of EngineeringModel that will be created from the request
sourceKind = Kind of EngineeringModel of referenced source EngineeringModelSetup

CopyAll = copy all data (incl all iterations)
CopyLatest = copy latest data only (only active iteration)
CreateTemplate = create template from referenced engineering model setup (study)

// invalid instantiations:
    if (newKind == 'MODEL_CATALOGUE' && sourceKind == 'STUDY_MODEL')    
        -> throw 'May not create MODEL_CATALOGUE from STUDY_MODEL.'

    if (newKind == 'TEMPLATE_MODEL' && sourceKind == 'MODEL_CATALOGUE')
        -> throw 'May not create TEMPLATE_MODEL from MODEL_CATALOGUE.'

    if(newKind == 'SCRATCH_MODEL' && sourceKind == 'MODEL_CATALOGUE')
        -> throw 'May not create SCRATCH_MODEL from MODEL_CATALOGUE.'

// determine instantiation mode by fallthrough logic:   
    -> CopyAll = false
    -> CopyLatest = false
    -> CreateTemplate = false

    if (newKind == 'STUDY_MODEL')
        -> CopyAll = true

    else if (newKind == 'TEMPLATE_MODEL' && sourceKind == 'STUDY_MODEL') 
        -> CreateTemplate = true

    else
        // newKind == 'MODEL_CATALOGUE' 
        // newKind == 'TEMPLATE_MODEL' 
        // newKind == 'SCRATCH_MODEL')
        -> CopyLatest = true

IterationSetup

It is forbidden to include an Iteration in the _create or _delete part of a POST message. An Iteration is created as a side-effect of a creation of an IterationSetup. When an IterationSetup is created the CDP4 WebServices will:

Glossary and Terms

When a Glossary is updated and the isDeprecated property is set to true, then all the isDeprecated of the Term instances contained by that Glossary will be set to true as well.

ParameterValueSet

It is forbidden to include an ParameterValueSet in the _create or _delete part of a POST message. ParameterValueSet instances are created and deleted as side-effects of different create, delete and update operations:

The values of the ParameterValueSet should be set as follows:

ParameterOverrideValueSet

It is forbidden to include an ParameterOverrideValueSet in the _create or _delete part of a POST message. ParameterOverrideValueSet instances are created and deleted as side-effects of different create, delete and update operations. A ParameterOverrideValueSet is created when a ParameterOverride is created. A ParameterOverride references the Parameter that it overrides. The side-effects specifed for the ParameterValueSet are valid for the ParameterOverrideValueSet as well.

ParameterSubscriptionValueSet

It is forbidden to include an ParameterSubscriptionValueSet in the _create or _delete part of a POST message. ParameterSubscriptionValuSet instances are created and deleted as side-effects of different create, delete and update operations. A ParameterSubscriptionValueSet is created when a ParameterSubscription is created. A ParameterSubscription is contained by the Parameter or ParameterOverride that it subscribes to. The side-effects specifed for the ParameterValueSet and ParameterOverrideValueSet are valid for the ParameterSubscriptionValueSet as well.

Possible and Actual Finite States

It is forbidden to include an ActualState in the _create or _delete part of a POST message. ActualState instances are created and deleted as side-effects of different create, delete and update operations.

Last modified 3 years ago.

^ Top