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": []
}
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"
}
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": []
}
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.
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:
EngineeringModelSetup
Participant
that references the Person
that has performed the POST requestDomainOfExpertise
to the activeDomain
property of the EnineeringModelSetup
of the Person
that has performed the POST request 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.
An EngineeringModelSetup
can be instantiated from a source model by:
Iid
of the EngineeringModelSetup
and the requiredRdl as blank when performing a Create POST.
In this mode the web server will create/instantiate the requiredRdl (ModelReferenceDataLibrary
) from the source 'EngineeringModelSetup` by the server.Depending on the EngineeringModelKind
of 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
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:
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.
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:
A ParameterValueSet is created when a state dependent Parameter exists and a PossibleState is added to the PossibleFinitestateList that is included in the ActualStateList that is referenced by the Parameter
A ParameterValueSet is deleted when the container Parameter is deleted.
The values of the ParameterValueSet should be set as follows:
-
.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.
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.
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.
An ActualState is created when a PossibleFinitestateList is added to the PossibleFinitestateList that are being referenced by an ActualStateList. As many ActualState instances are created as new combinations of PossibleFinitestate instances can be created.
An ActualState is deleted when the ActualStateList is deleted that is the container of the ActualState.
Last modified 4 years ago.