CDP 4 User Manual

Retrieving Data

In order to retrieve any data from the CDP4 WebServices a GET request must be performed. Starting with the first TopContainer SiteDirectory, a GET request on the following URI must be performed.

http://hostname:port/SiteDirectory

This query will return a shallow copy of the SiteDirectory object in a JSON format. The CDP4 Web API always returns an array of objects, even if only one object was requested. En example of a GET request on a SiteDirectory is shown below:

[
{
    "revisionNumber": 1,
    "classKind": "SiteDirectory",
    "organization": [],
    "person": [
      "77791b12-4c2c-4499-93fa-869df3692d22"
    ],
    "participantRole": [
      "ee3ae5ff-ac5e-4957-bab1-7698fba2a267"
    ],
    "defaultParticipantRole": "ee3ae5ff-ac5e-4957-bab1-7698fba2a267",
    "siteReferenceDataLibrary": [
      "c454c687-ba3e-44c4-86bc-44544b2c7880"
    ],
    "model": [ 
      "116f6253-89bb-47d4-aa24-d11d197e43c9" 
    ],
    "personRole": [
      "2428f4d9-f26d-4112-9d56-1c940748df69"
    ],
    "defaultPersonRole": "2428f4d9-f26d-4112-9d56-1c940748df69",
    "logEntry": [],
    "domainGroup": [],
    "domain": [
      "0e92edde-fdff-41db-9b1d-f2e484f12535"
    ],
    "naturalLanguage": [],
    "createdOn": "2016-09-01T08:14:45.461Z",
    "name": "Test Site Directory",
    "shortName": "TEST-SiteDir",
    "lastModifiedOn": "2015-04-17T07:48:14.56Z",
    "iid": "f13de6f8-b03a-46e7-a492-53b2f260f294"
  }
]

All the classes in the CDP4 UML model derive from the Thing class. The Thing class is an abstract super class that has 3 properties:

When inspecting the sample JSON object we notice scalar properties as well as compound properties. The compound properties always contain the unique id's of the objects that are contained (through a composite aggregation), or referenced. The unique id's are representative of pointers or references to these objects. Scalar properties can either be a single unique id pointer to another object; or a string, number, true, false or null. See json.org for more information on how JSON. The iid property of the Thing class is of type UUID. The string representation of UUID must be in accordance with the following regular expression:

[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[a-b8-9][a-f0-9]{3}-[a-f0-9]{12}

Extent query parameter

The CDP4 Web API supports a query parmeter called extent that has as possible values shallow (the default value) and deep. When the query parameter is not used a shallow copy of the requested resource is returned. When the query parameter is added to the URI of the resource, and it's value is set to deep, the CDP4 Web API returns all the objects that are contained by the requested object, all the way down the containment hierarchy. The JSON objects that are returned are returned as a JSON array of shallow copies, the CDP4 Web API does not return nested objects.

http://hostname:port/SiteDirectory?extent=deep

Even though the unique id of the SiteDirectory was not provided, the object will still be returned. This is due to the fact that there is only one instance. From the sample JSON object listed above we can find the unique id of the SiteDirectory : "f13de6f8-b03a-46e7-a492-53b2f260f294". When we add this unique id to the URI the same object will be returned from the CDP4 Web API

http://hostname:port/SiteDirectory/f13de6f8-b03a-46e7-a492-53b2f260f294

Containment Queries

The CDP4 Web API is case sensitive. Only the TopContainers in the URI shall start with an upper case character. To query any of the objects that are contained by the SiteDirectory the property name must be included in the URI. The following query returns all the Person objects that are contained by the SiteDirectory:

http://hostname:port/SiteDirectory/f13de6f8-b03a-46e7-a492-53b2f260f294/person

The response is as follows:

[
  {
    "revisionNumber": 2,
    "classKind": "Person",
    "organization": null,
    "givenName": "John",
    "surname": "Doe",
    "organizationalUnit": "",
    "emailAddress": [],
    "telephoneNumber": [],
    "defaultDomain": "0e92edde-fdff-41db-9b1d-f2e484f12535",
    "isActive": true,
    "role": "2428f4d9-f26d-4112-9d56-1c940748df69",
    "password": "01fbc7972dacd0cf2c9d8f798a73af76186e9b42f865f03539806a156a57c52b",
    "defaultEmailAddress": null,
    "defaultTelephoneNumber": null,
    "userPreference": [],
    "shortName": "admin",
    "isDeprecated": false,
    "iid": "77791b12-4c2c-4499-93fa-869df3692d22"
  }
]

In the example only one Person object is contained by the SiteDirectory, if more Person objects would have been contained, of course more objects would have been returned. Again, a response from the CDP4 WebServices is always in the form of a JSON array.

To query a specific instance, it's unique id needs to be added to the URI. Following the Person example above, the query is as follows:

http://hostname:port/SiteDirectory/f13de6f8-b03a-46e7-a492-53b2f260f294/person/77791b12-4c2c-4499-93fa-869df3692d22

More deeply contained objects can of course be returned as well; A Person object can contain zero or more EmailAddress instances, to query the email address of the Person object the following query can be performed:

http://hostname:port/SiteDirectory/f13de6f8-b03a-46e7-a492-53b2f260f294/person/77791b12-4c2c-4499-93fa-869df3692d22/emailAddress

includeAllContainers Query Parameter

When an object along the containment hierarchy is queried, see the Person and EmailAddress sample queries, the containers of these objects are not returned. Looking at the response of the Person query, only the Person object was returned, not the SiteDirectory object. The CDP4 Web API can return all the shallow copies of objects up the containment tree. This can be achieved by using the includeAllContainers query parameter. It has as values true and false, the default value is false.

The following query will return the Person object as well as it's container(s), which in this case is also the SiteDirectory.

http://hostname:port/SiteDirectory/f13de6f8-b03a-46e7-a492-53b2f260f294/person/77791b12-4c2c-4499-93fa-869df3692d22?includeAllContainers=true

revisionNumber Query Parameter

The data that is accessible thorugh the CDP4 WebServices is versioned. To minimize the required traffic it is possible to perform a GET request that only returns those objects that have a revision number that is higher than a specified revision number. The revisionNumber query parameter is used for this purpose. The revisionNumber query parameter is an integer that must be greater than or equal to zero. Executing a GET request and specifying a value of zero for the revisionNumber query parameter returns the same result as the GET without the revisionNumber query parameter.

The following query will return all the objects that are in the containment tree of the SiteDirectory that have a revision number that is greater than 2:

http://hostname:port/SiteDirectory/f13de6f8-b03a-46e7-a492-53b2f260f294?revisionNumber=2

The revisionNumber query parameter may not be used in combination with any of the other query parameters. It may however be used in combination with a POST request. The result of a POST request including the revisionNumber query parameter is an array of all the objects that have a revision number that is higher than the value of the revisionNumber query parameter.

revisionHistory Query Parameter

Every change to any object is versioned therefore the state of an object an any point in time, and it's complete containment tree, can be retrieved from the CDP WebServices. The revisionHistory parameter has not yet been implemented.

includeFileData Query Parameter

The CDP4 data model contains concepts that represent a filesystem containing folders and files. The FileRevision class represents a persisted revision of a File. The CDP4 Web API supports HTTP multipart requests to send and retrieve the content of the files. In order to retrieve files from the CDP4 Web API the includeFileData query parameter must be used. The includeFileData query parameter has as possible value true and false, the default value is equal to false. When the includeFileData query parameter is included and it's value is set to true the response will include JSON data as well as the file content in the form of a multipart message.

The following query will return all the data contained by an Iteration including the content of the FileRevision objects:

http://hostname:port/EngineeringModel/{iid}/Iteration/{iid}?content=deep&includeFileData=true 

Protocol and Software Version

The CDP4 Web API exposes version information regarding versions of the software and the CDP4 Web API protocol. The following HTTP headers are used to return this information with every response:

Accessing an EngineeringModel

The EngineeringModel class is a TopContainer. It contains all the concepts to model both the requirements of a system-of-interest and the solution. An EngineeringModel contains 1 or more Iterations. An Iteration is a version of the EngineeringModel that represents one complete and coherent step in the development of the EngineeringModel. This means that the actual engieering data of an EngineeringModel is contained in an Iteration. To retrieve the data from an Iteration the following GET request must be performed:

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

This will return the shallow copy of the Iteration. To include the contained items the following GET query must be executed:

http://hostname:port/EngineeringModel/{iid}/iteration/{iid}?extent=deep

Last modified 11 months ago.

^ Top