Data Service

Release Notes

1.5.0
Features
  • Endpoint for clearing a part.

Interface Information

Endpoints

Information about supported interface version can be fetched calling the root endpoint of DataService:

Example Example: Get interface version for Data Service
Request
GET /dataServiceRest/ HTTP/1.1
Response
{"supportedVersions":["1.4.2"]}

Object Structure

Interface information returns the highest available minor version of each major version. This lets the user decide which features can be used. As a minor version is backwards compatible to all previous minor versions, there is no point in enumerating them all. An user want to know which revision of each major version is available as that means they can work around possible bugs of older revisions.

Service Information

Endpoints

The service information can be fetched using the following endpoint. This endpoint doesn’t provide filter parameters.

Example Example: Get Service Information for a given connection
Request
GET /dataServiceRest/serviceInformation HTTP/1.1
Response
{
   "serverName": "PiWeb Server",
   "version": "5.6.2.0",
   "securityEnabled": false,
   "edition": "PiWebDB",
   "versionWsdlMajor": "2",
   "versionWsdlMinor": "9",
   "partCount": 4,
   "characteristicCount": 125,
   "measurementCount": 20,
   "valueCount": 900,
   "featureList":
   [
      "MeasurementAggregation",
      "DistinctMeasurementSearch"
   ],
   "inspectionPlanTimestamp": "2014-11-24T16:08:58.812964+01:00",
   "measurementTimestamp": "2014-11-03T10:27:28.3461853+01:00",
   "configurationTimestamp": "2014-11-03T10:27:27.5245116+01:00"
}

Object Structure

Service information requests always have the smallest response time and are therefore well suited for checking the connection. Fetching the service information doesn’t require authentication.

The returned ServiceInformation object has the following properties:

Property Description
string serverName The name of the PiWeb server as specified in the server settings
string version The version number of the PiWeb server
bool securityEnabled Indicates whether authentication is required by the server
string edition The database edition. Usually this is “PiWebDB”
string versionWsdlMajor The major version number of the interface
string versionWsdlMinor The minor version number of the interface
int partCount The estimated number of parts stored on the server
int characteristicCount The estimated number of characteristics stored on the server
int measurementCount The estimated number of measurements stored on the server
int valueCount The estimated number of measured values stored on the server
Features featureList A list of features supported by the server. This can be MeasurementAggregation or DistinctMeasurementSearch
DateTime inspectionPlanTimestamp Timestamp of the last inspection plan modification
DateTime measurementTimestamp Timestamp of the last measurement modification
DateTime configurationTimestamp Timestamp of the last configuration modification
DateTime catalogTimestamp Timestamp of the last catalog modification

Info A partCount, characteristicCount, measurementCount or valueCount of -1 means that no statistics have been calculated yet.

Configuration

Endpoints

The configuration can be fetched, created, updated and deleted using the following endpoints. These endpoints do not provide filter parameters.

Example Example: Fetching the configuration including all attributes
Request
GET /dataServiceRest/configuration HTTP/1.1
Response
{
       "partAttributes":
       [
        {
            "key":1001,
            "description":"partNumber",
            "length":30,
            "type":"AlphaNumeric",
            "definitionType":"AttributeDefinition"
        },
        ...
       ],
       "characteristicAttributes":
       [
        {
            "key":2001,
            "description":"characteristicNumber",
            "length":20,
            "type":"AlphaNumeric",
            "definitionType":"AttributeDefinition"
        },
        ...
       ],
       "measurementAttributes":
       {
             "key": 8,
             "description": "inspector",
             "catalog": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
             "definitionType": "CatalogAttributeDefinition"
       ...
       },
       "valueAttributes":
       {
       ...
       },
       "catalogAttributes":
       {
       ...
       }
}

Creates the attribute definitions transfered within the body of the request for the given :entityType which must be part of the uri

Example Example: Adding a part attribute with the key 1001 to the configuration
Request
POST /dataServiceRest/configuration/part HTTP/1.1
[
  {
    "key":1001,
    "description":"partNumber",
    "length":30,
    "type":"AlphaNumeric",
    "definitionType":"AttributeDefinition"
  }
]
Response
HTTP/1.1 201 Created

Updates the attribute definitions transfered within the body of the request for the given :entityType which must be part of the uri

Example Example: Updating the part attribute with key 1001 - change length from 30 to 50
Request
PUT /dataServiceRest/configuration/part HTTP/1.1
[
  {
    "key":1001,
    "description":"partNumber",
    "length":50,
    "type":"AlphaNumeric",
    "definitionType":"AttributeDefinition"
  }
]
Response
HTTP/1.1 200 Ok
Example Example: Delete all attributes of the current configuration
Request
DELETE /dataServiceRest/configuration HTTP/1.1
Response
HTTP/1.1 200 Ok

Deletes all attribute definitions of which the id is in the :attributeIdList for the specified :entityType. If :attributeIdList is not specified, the request deletes all attributes of the :entityType.

Example Example: Delete the part attributes with the keys 1001 and 1002
Request
DELETE /dataServiceRest/configuration/part/{1001, 1002} HTTP/1.1
Response
HTTP/1.1 200 Ok


If at least one entry with value for the given key exists HTTP status code 204 otherwise 404 is returned.

Object Structure

The PiWeb configuration consists of a list of attributes for each entity type. The different entity types are:

  • part,
  • characteristic,
  • measurement,
  • value and
  • catalog.

The attributes are either AttributeDefinition or CatalogAttributeDefinition.

AttributeDefinition

Property Description
ushort key The attribute’s key, which serves as a unique id
string description The attribute’s name or a short description
AttributeType type The attribute’s type. AlphaNumeric, Integer, Float or DateTime
ushort length The attribute’s maximum length. Only set if the type is AlphaNumeric
string definitionType Always has the value ‘AttributeDefinition’ and is used to differentiate between AttributeDefinition and CatalogAttributeDefinition

CatalogAttributeDefinition

Property Description
ushort key The attribute’s key, which serves as a unique id
string description The attribute’s name or a short description
Guid catalog The id of the catalog that contains the possible attribute values
string definitionType Always has the value ‘CatalogAttributeDefinition’ and is used to differentiate between AttributeDefinition and CatalogAttributeDefinition

Catalogs

Endpoints

Catalogs and catalog entries can be fetched, created, updated and deleted using the following endpoints.

Example Example: Fetching all catalogs
Request
GET /dataServiceRest/catalogs HTTP/1.1
Response
[
   {
      "uuid": "d7291afb-0a67-4c1e-8bcc-6fc455bcc0e5",
      "name": "direction catalog",
      "validAttributes": [ 2009 ],
      "catalogEntries":
      [
         {
            "key": 0,
            "attributes": { "2009": "undefined" }
         },
         {
            "key": 1,
            "attributes": { "2009": "right" }
         },
         {
            "key": 2,
            "attributes": { "2009": "left" }
         }
      ]
   },
   {
      "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
      "name": "InspectorCatalog",
      "validAttributes": [ 4092, 4093 ],
      "catalogEntries":
      [
         {
            "key": 0,
            "attributes": { "4092": "n.def.", "4093": "n.def." }
         },
         {
            "key": 1,
            "attributes": { "4092": "21", "4093": "Smith" }
         },
         {
            "key": 2,
            "attributes": { "4092": "20", "4093": "Miller" }
         },
         {
            "key": 3,
            "attributes": { "4092": "23", "4093": "Williams" }
         }
      ]
   },
   ...
]
Example Example: Fetching the catalog with the uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
GET /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad HTTP/1.1
Response
[
    {
        "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
        "name": "InspectorCatalog",
        "validAttributes": [ 4092, 4093 ],
        "catalogEntries":
        [
            {
                "key": 0,
                "attributes": { "4092": "n.def.", "4093": "n.def." }
            },
            {
                "key": 1,
                "attributes": { "4092": "21", "4093": "Smith" }
            },
            {
                "key": 2,
                "attributes": { "4092": "20", "4093": "Miller" }
            },
            {
                "key": 3,
                "attributes": { "4092": "23", "4093": "Williams" }
            }
         ]
     }
]

To create a new catalog, the catalog object must be transmitted in the request’s body. A valid request contains a unique identifier, the catalog name and the valid attributes. Catalog entries are optional. All valid attributes must be added as catalog attributes beforehand (see Configuration).

Info If no catalog entries are specified, an empty catalog entry with key ‘0’ and attribute value(s) ‘not defined’ ( in case of alphanumeric attributes ) is created by default.

Info If catalog entries are specified setting -1 as catalog entry’s key leads server to generate a new unique key for that entry.

Example Example: Adding the catalog InspectorCatalog
Request
POST /dataServiceRest/catalogs HTTP/1.1
[
  {
           "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
           "name": "InspectorCatalog",
           "validAttributes": [ 4092, 4093 ],
           "catalogEntries":
           [
               {
                   "key": 0,
                   "attributes": { "4092": "n.def.", "4093": "n.def." }
               },
               {
                   "key": 1,
                   "attributes": { "4092": "21", "4093": "Smith" }
               },
               {
                   "key": 2,
                   "attributes": { "4092": "20", "4093": "Miller" }
               },
               {
                   "key": -1,  //Server will generate an unique key
                   "attributes": { "4092": "23", "4093": "Williams" }
               }
            ]
        }
]
Response
HTTP/1.1 201 Created

Info Setting -1 as catalog entry’s key leads server to generate a new unique key for that entry. %}

To add entries to an existing catalog they need to be specified in the request body. Each new entry must consist of a unique key. Each entry attribute must be listed as a valid attribute in the catalog definition.

Example Example: Adding a catalog entry - add the inspector ‘Clarks’
Request
POST /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad HTTP/1.1
 [
   {
       "key": 4,
       "attributes": { "4092": "22", "4093": "Clarks" }
   }
 ]
Response
HTTP/1.1 201 Created

Update a catalog when you want to:

  • rename the catalog and/or
  • update existing catalog entries and/or
  • update catalog’s valid attributes.

To update a catalog, the whole object, including the valid attributes, needs to be transmitted in the body of the HTTP request.

Example Example: Rename the catalog from ‘InspectorCatalog’ to ‘Inspectors’ and change the inspector’s name from ‘Smith’ to ‘Clarks’
Request
PUT /dataServiceRest/catalogs HTTP/1.1
[
  {
           "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
           "name": "Inspectors",
           "catalogEntries":
           [
               {
                   "key": 0,
                   "attributes": { "4092": "n.def.", "4093": "n.def." }
               },
               {
                   "key": 1,
                   "attributes": { "4092": "21", "4093": "Clarks" }
               },
               {
                   "key": 2,
                   "attributes": { "4092": "20", "4093": "Miller" }
               },
               {
                   "key": 3,
                   "attributes": { "4092": "23", "4093": "Williams" }
               }
            ]
        }
]
Response
HTTP/1.1 200 Ok
Example Example: Delete all catalogs
Request
DELETE /dataServiceRest/catalogs HTTP/1.1
Response
HTTP/1.1 200 Ok
Example Example: Delete the catalog with uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
DELETE /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad HTTP/1.1
Response
HTTP/1.1 200 Ok
Example Example: Delete all entries from the catalog with uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
DELETE /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad/ HTTP/1.1
Response
HTTP/1.1 200 Ok
Example Example: Delete the entries with key 1 and 3 from the catalog with uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
DELETE /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad/{1,3} HTTP/1.1
Response
HTTP/1.1 200 Ok

Object Structure

Each catalog describes a list of entries. All entries have the same defined set of attributes, called valid attributes. All valid attributes must be created as catalog attributes beforehand. Catalog and CatalogEntryhave the following structures:

Catalog

Property Description
Guid uuid Identifies the catalog uniquely
string name The name of the catalog
ushort[] validAttributes A list of attribute keys that are valid for this catalog
CatalogEntry catalogEntries A list of catalog entries

CatalogEntry

Property Description
short key Specifies the entry’s order within the catalog
Attribute[] attributes A list of attributes which consists of key and value. The keys must be in the validAttributes list.

Parts and Characteristics

Endpoints

You can fetch, create, update and delete parts and characteristics using the following endpoints:

Parts

You can fetch all parts or certain parts. Possible filter uri parameters are:

Parameter name Description
Guid list partUuids
 Restricts the query to the parts with these uuids.
Path partPath Restricts the query to the part with this path.
ushort depth
default: 1		 Determines how many levels of the inspection plan tree hierarchy should be fetched. Setting depth=0 means that only the entity itself should be fetched, depth=1 means the entity and its direct children should be fetched. Please note that depth is treated relative of the path depth of the provided part.
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedPartAttributes
default: All		 Restricts the query to the attributes that should be returned for parts, for example requestedPartAttributes={1001, 1008}.
Example Example: Fetch the part at path /metal part without child parts and only get the values for attributes 1001 and 1003
Request
GET /dataServiceRest/parts?partPath=/metal%20part&depth=0&requestedPartAttributes={1001,1003} HTTP/1.1
Response
[
   {
        "path": "P:/metal part/",
        "charChangeDate": "2014-11-19T10:48:32.917Z",
        "attributes": { "1001": "4466", "1003": "mp" },
        "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
        "version": 0,
        "timestamp": "2012-11-19T10:48:32.887Z"
    }
]

Versioning

If versioning is enabled, you can fetch the parts history using the parameter withHistory=true:

Request
GET /dataServiceRest/parts?partPath=/PartWithVersioning&withHistory=true HTTP/1.1
Response
[
    {
        "attributes": {
            "1001": "1758_e3"
        },
        "path": "P:/PartWithVersioning_edit/",
        "history": [
            {
                "attributes": {},
                "path": "P:/PartWithVersioning/",
                "charChangeDate": "2021-01-06T09:18:02.12Z",
                "uuid": "0c2c5bd1-4372-439c-9cdb-726841981daa",
                "comment": "[John Doe]: Part 'PartWithVersioning' created",
                "version": 415,
                "timestamp": "2021-01-06T09:18:02.12Z"
            }
        ],
        "charChangeDate": "2021-01-06T09:18:02.12Z",
        "uuid": "0c2c5bd1-4372-439c-9cdb-726841981daa",
        "comment": "[John Doe]: Part number Changed",
        "version": 421,
        "timestamp": "2021-01-06T09:54:31.583Z"
    }
]

When using this parameter each part will contain a history, where all previous changes of this part are stored. Each entry of the history contains the old values of the part at this time, and a comment with information about why and by whom the change was made. In above example we have one history entry, stating that the part ‘PartWithVersioning’ was created by user John Doe. Attributes where still empty. The current state contains the attribute 1001, and the comment further down tells us that someone changed it (1001 equals attribute ‘Part number’). If we add another attribute the history will extend with the current values, the set of history entries will now contain two entries. Please note that the version number is global for the PiWeb Server, so gaps simply mean that another part was edited in the meantime, and this is not the 415th version of the part.

You can fetch a certain part by its :partUuid. The result can be restricted by the following uri parameters:

Parameter name Description
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedPartAttributes
default: All		 Restricts the query to the attributes that should be returned for parts, for example requestedPartAttributes={1001, 1008}.
Example Example: Fetch the part ‘/metal part’ by its guid
Request
GET /dataServiceRest/parts/05040c4c-f0af-46b8-810e-30c0c00a379e HTTP/1.1
Response
{
    "path": "P:/metal part/",
    "charChangeDate": "2014-11-19T10:48:32.917Z",
    "attributes": {},
    "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
    "version": 0,
    "timestamp": "2012-11-19T10:48:32.887Z"
}

To create a new part, you must send its JSON representation in the request body. Values for uuid and path are required, attributes and comment are optional. The attribute keys must be valid part attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in the server settings.

Example Example: Adding the ‘metal part’ part with the uuid 05040c4c-f0af-46b8-810e-30c0c00a379e
Request
POST /dataServiceRest/parts HTTP/1.1
[
  {
    "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
    "path": "P:/metal part/",
    "attributes": { "1001": "4466", "1003": "mp" }       
  }
]
Response
HTTP/1.1 201 Created

If you update a part you might want to:

  • Rename/move parts or
  • change attributes of parts.

If versioning is activated on the server side, every update creates a new version entry. You should add a value for comment to explain why it was changed and by whom. The optimal format is “[Username]:Reason of change”, e.g. “[John Doe]: Renamed ‘Part1’ to ‘Part2’”. This way it will be correctly displayed in PiWeb Planner.

Info If versioning is set to ‘Controlled by the client’ on server side it can be controlled by the following parameter:

Parameter name Description
bool versioningEnabled
default: false		 Determines whether a version entry should be created or not. This only effects the query if versioning is set to ‘Controlled by the client’ on server side.
Example Example: Change the metal part’s attributes
Request
PUT /dataServiceRest/parts HTTP/1.1
[
  {
     "path": "P:/metal part/",
     "attributes": { "1001": "4469", "1003": "metalpart" }       
     "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
  }
]
Response
HTTP/1.1 200 Ok

There are two ways to delete parts, either by their path or by their uuids. This means that either the filter parameter partPath or partUuids has to be set:

Parameter name Description
Guid list partUuids
 Restricts the query to the parts with these uuids.
Path partPath Restricts the query to the part with this path.

In both cases the request deletes the part itself as well as all its child parts and child characteristics. If both parameters are set only the partUuids parameter will be considered.

Info If option “Parts with measurement data can be deleted” is deactivated parts containing measurements will not be deleted.

Example Example: Delete the part ‘metal part’ and its children.
Request
DELETE /dataServiceRest/parts?partPath=/metal%20part HTTP/1.1
Response
HTTP/1.1 200 Ok

Deleting a part also deletes all its children.

Info If option “Parts with measurement data can be deleted” is deactivated parts containing measurements will not be deleted.

Example Example: Delete the part ‘metal part’ and all entities beneath it by the part’s guid
Request
DELETE /dataServiceRest/parts/05040c4c-f0af-46b8-810e-30c0c00a379e HTTP/1.1
Response
HTTP/1.1 200 Ok

To clear a part, you need to specify it by its uuid via uri segment. Clearing a part results in keeping the given part as well as its raw data and deleting all subParts, measurements, values and all other raw data. If optional keep parameter is set to value subParts subPart (including child items, measurements, values and raw data) are not deleted as well.

Example Example: Clearing the ‘metal part’ part with the uuid 05040c4c-f0af-46b8-810e-30c0c00a379e but keep all subParts.
Request
POST /dataServiceRest/parts/05040c4c-f0af-46b8-810e-30c0c00a379e/clear?keep=subParts HTTP/1.1
Response
HTTP/1.1 200 Ok

Characteristics

You can fetch all characteristics or only the characteristics described by the uri parameters. Possible filter uri parameters are:

Parameter name Description
Guid list charUuids
 Restricts the query to the characteristics with these uuids.
Path partPath
default: /		 Restricts the query to the part with this path. The charUuids parameter takes precedence over this parameter.
ushort depth
default: 65.536		 Determines how many levels of the inspection plan tree hierarchy should be fetched. Setting depth=0 means that only the entity itself should be fetched, depth=1 means the entity and its direct children should be fetched. Please note that depth is treated relative of the path depth of the provided part or characteristic.
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedCharacteristicAttributes
default: All		 Restricts the query to the attributes that should be returned for characteristics, for example requestedCharacteristicAttributes={2001, 2101}

InfoYou can only request direct characteristics of the part, characteristics of child parts will be ignored.

Example Example: Fetch all characteristics beneath the part ‘/metal part’ until depth=2
Request
GET /dataServiceRest/characteristics?partPath=/metal%20part&depth=2 HTTP/1.1
Response
[
   {
        "path": "PC:/metal part/deviation_3/",
        "attributes": { ... },
        "uuid": "27e23a7c-dbe7-4863-8461-6abf7b03ddd7",
        "version": 0,
        "timestamp": "2012-11-19T10:48:32.887Z"
    },
   {
        "path": "PCC:/metal part/deviation_3/.X/",
        "attributes": { ... },
        "uuid": "51c8568a-9410-465a-a8ed-33063db41dac",
        "version": 0,
        "timestamp": "2015-03-24T08:17:28.03Z"
    },
    {
        "path": "PCC:/metal part/deviation_3/.Y/",
        "attributes": { ... },
        "uuid": "b7a30736-6e89-4dd5-9bc0-e6cb9eb5e2da",
        "version": 0,
        "timestamp": "2015-03-24T08:17:34.61Z"
    },
    {
        "path": "PCC:/metal part/deviation_3/.Z/",
        "attributes": { ... },
        "uuid": "1175919c-5c59-487e-a0fb-deac04510046",
        "version": 0,
        "timestamp": "2015-03-24T08:17:38.423Z"
    }
]

Versioning works the same way as with parts, described in the first endpoint GET /parts.

The result of fetching a certain characteristic by its :charUuid can be restricted by the following uri parameters:

Parameter name Description
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedCharacteristicAttributes
default: All		 Restricts the query to the attributes that should be returned for characteristics, for example requestedCharacteristicAttributes={2001, 2101}
Example Example: Fetch the characteristic ‘/metal part/deviation_3’ by its guid
Request
GET /dataServiceRest/characteristics/27e23a7c-dbe7-4863-8461-6abf7b03ddd7 HTTP/1.1
Response
{
    "path": "PC:/metal part/deviation_3/",
    "attributes": { ... },
    "uuid": "27e23a7c-dbe7-4863-8461-6abf7b03ddd7",
    "version": 0,
    "timestamp": "2012-11-19T10:48:32.887Z"
}

To create characteristics, you must send a JSON representation of the characteristics in the request body. Values for uuid and path are required, attributes and comment are optional. The attribute keys must be valid characteristic attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in the server settings.

Example Example: Adding the characteristic ‘metal part/deviation_3’
Request
POST /dataServiceRest/characteristics HTTP/1.1
[
  {
     "path": "PC:/metal part/deviation_3/",
     "attributes":
      {
         "2004": "3",
         "2101": "0",
         "2110": "-0.5",
         "2111": "0.5"
      },
     "uuid": "27e23a7c-dbe7-4863-8461-6abf7b03ddd7"
  }
]
Response
HTTP/1.1 201 Created

If you update characteristics you want to:

  • Rename/move characteristics or
  • change attributes of characteristics.

If versioning is activated on the server side, every update creates a new version entry. You should add a value for comment to explain why it was changed and by whom. The optimal format is “[Username]:Reason of change”, e.g. “[John Doe]: Renamed ‘Characteristic1’ to ‘Characteristic2’”. This way it will be correctly displayed in PiWeb Planner.

Info If versioning is set to ‘Controlled by the client’ on server side it can be controlled by the following parameter:

Parameter name Description
bool versioningEnabled
default: false		 Determines whether a version entry should be created or not. This only effects the query if versioning is set to ‘Controlled by the client’ on server side.
Example Example: Change the metal part/deviation_3’s attributes
Request
PUT /dataServiceRest/characteristics HTTP/1.1
[
  {
     "path": "PC:/metal part/deviation_3/",
     "attributes": { "2110": "-1.0", "2111": "1.0"  }       
     "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
  }
]
Response
HTTP/1.1 200 Ok

You have two options to delete characteristics, either by their paths or by their uuids. This means that either the filter parameter charPath or charUuids has to be set:

Parameter name Description
Guid listcharUuids
 Restricts the query to characteristics with these uuids.
Path charPath Restricts the query to the part with this characteristics.

In both cases the request deletes the characteristic itself as well as all its children. If both parameters are set only the charUuids parameter will be considered.

Example Example: Delete the characteristic ‘metal part/deviation_3’ and all entities beneath it
Request
DELETE /dataServiceRest/parts?charPath=/metal%20part/deviation_3 HTTP/1.1
Response
HTTP/1.1 200 Ok

Deleting a characteristic also deletes all its children.

Example Example: Delete the characteristic ‘metal part/deviation_3’ and all entities beneath it by its guid
Request
DELETE /dataServiceRest/characteristics/27e23a7c-dbe7-4863-8461-6abf7b03ddd7 HTTP/1.1
Response
HTTP/1.1 200 Ok


Object Structure

Both parts and characteristics are PiWeb inspection plan entities. They have the following properties:

Property Description
Guid uuid Identifies this inspection plan entity uniquely.
string path The path of this entity. It consists of the path’s hierarchical structure followed by the path itself, e.g. PCC:/metal part/deviation_3/.X/. P stands for part and C for characteristic. The path always ends with /.
Attribute attributes A set of attributes which describe the entity.
string comment A comment which describes the last inspection plan change. The comment is only returned in case versioning is enabled in the server settings.
int version Contains the entity´s revision number. The revision number starts with 0 and is incremented by 1 each time changes are applied to the inspection plan.
dateTime timeStamp Contains the date and time of when the entity was last updated.
dateTime charChangeDate (Parts only) The timestamp for the most recent characteristic change on any characteristic that belongs to this part

Measurements and Values

Endpoints

You can fetch, create, update and delete measurements and values using the following endpoints:

Info Endpoint Measurements creates measurements without measured values. Values sent to this endpoint are ignored and won’t get saved! Always use the Values enpoint when creating or updating measurements with values!

Measurements

You can fetch all measurements or certain measurements only. Possible filter uri parameters are:

Type Parameter Description
Example
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part
partPath=/metal%20part
bool deep
default: false		 Determines whether the query should affect all levels of the inspection plan.
deep=true
OrderCriteria order
default: 4 desc		 Determines which attribute keys and which direction the keys should be ordered by
order=4 asc, 10 desc
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. It can be necessary to encode ‘+’ as ‘%2B’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
DateTime fromModificationDate Specifies a date to select all measurements that where modified after that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
DateTime toModificationDate Specifies a date to select all measurements that where modified before that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
int limitResult Restricts the number of result items.
limitResult=100
UShort list requestedMeasurementAttributes
default: All attributes		 Restricts the query to the attributes that should be returned for measurements. Use an empty list {} to return no attributes.
requestedMeasurementAttributes={4,8}
None, Simple, Detailed statistics
default: None		 Indicates how statistical informtaion should be returned:
None = Return no information
Simple = Return statistical information including number of characteristics out of warning limit, number of characteristics out of tolerance and number of characteristics in warning limit and tolerance
Detailed = Return statistical information the same way as Simple plus the guid for each characteristic
statistics=Simple
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
int List mergeAttributes Specifies the list of primary measurement keys to be used for joining measurements accross multiple parts on the server side. (Please find more detailed information below.)
mergeAttributes=4,6
None, MeasurementsInAtLeastTwoParts, MeasurementsInAllParts mergeCondition
default: MeasurementsInAllParts		 Specifies the condition that must be adhered to when merging measurements accross multiple parts using a primary key. (Please find more detailed information below.)
Guid mergeMasterPart Specifies the part to be used as master part when merging measurements accross multiple parts using a primary key. (Please find more detailed information below.)

Using the primary measurement key

The primary measurement key can be used to filter and fetch multiple measurements of the same physical part. This is a common use case when parts are measured multiple times on different machines or assembly stages.

PiWeb allows you to filter your measurement query on server side, so the returned result set contains exactly the data you need. Three new parameters are introduced to the query:

Parameter Description
mergeAttributes A list of attribute keys, by which the measurements are grouped. Currently, you can only specify one attribute.
mergeCondition Specifies whether the primary measurement key has to appear in only one or multiple parts
mergeMasterPart Specifies the part on which PiWeb searches for distinct values of the primary key attribute

In this documentation, we are going to work with the following little measurement table:

Please note that these are measurements from three different inspection plan parts which are identified by attribute 14, which has the name Key. In the following examples, all returned measurements will be highlighted. The number in the row headers indicates pivot rows, while the matching color highlights measurements, that are returned because they match a primary measurement key of a pivot row.

1. Fetching measurements without primary measurement key

A very basic query to this measurement table would look like the following:

Full query: /measurements?order=4 desc&limitResult=3
orderBy 4
limitResult 3

This query will fetch the last 3 measurements of all parts. The result set contains two different physical parts with the Key Y and O, on two different inspection plan parts Assembly and Cmm.

2. Adding the paramter mergeAttributes

In our example, we are using attribute 14 as our primary measurement key. PiWeb will only return measurements, that have a value for the primary measurement key that exists in all specified parts. You can change this behavior later.

Info PiWeb needs the parameter partUuids to be specified when applying the primary measurement keys. Querys with the parameter partPath specified and the parameter deep set to true are not allowed.

Full query: /measurements?order=4 desc&limitResult=3&partUuids={uuid1,uuid2,uuid3}&mergeAttributes={14}
mergeAttributes {14}
mergeCondition MeasurementsInAllParts (default)
mergeMasterPart null (default)

The query returns three measurements with the Key O since it’s the only key that appears in all three parts, Assembly, Cmm and Inline.

3. Adding the parameter mergeCondition with value MeasurementsInAtLeastTwoParts

Compared to the last query, the result will also include measurements with keys, that appear in only two parts.

Full query: /measurements?order=4 desc&limitResult=3&partUuids={uuid1,uuid2,uuid3}&mergeAttributes={14}&mergeCondition=MeasurementsInAtLeastTwoParts
mergeAttributes {14}
mergeCondition MeasurementsInAtLeastTwoParts
mergeMasterPart null (default)

The result set contains measurements with the keys O and J because the measurements with unique keys Y and S are filtered out.

4. Adding the parameter mergeCondition with value None

Setting the mergeCondition to None will result in single, non-matched measurements to be returned.

Full query: /measurements?order=4 desc&limitResult=3&partUuids={uuid1,uuid2,uuid3}&mergeAttributes={14}&mergeCondition=None
mergeAttributes {14}
mergeCondition None
mergeMasterPart null (default)

All measurements will be returned, only limited by the parameter limitResult which is set to 3. Therefore, all measurements of the three most recently measured keys will be returned.

5. Adding the parameter mergeMasterPart with the uuid of Inline

When the parameter mergeMasterPart is set, PiWeb will search for unique values of the primary measurement key only on measurements of the specified part. Measurements that are not measured on the specified part will therefore be filtered.

Full query: /measurements?order=4 desc&limitResult=3&partUuids={uuid1,uuid2,uuid3}&mergeAttributes={14}&mergeCondition=None&mergeMasterPart=uuid
mergeAttributes {14}
mergeCondition None
mergeMasterPart uuid of part 'Inline'

As you noticed, the measurements with the keys Y and J are not included in the result set, because none of them is measured on the master part Inline.

Example Example: Fetch measurements newer than 01.01.2015 for the part with the guid e42c5327-6258-4c4c-b3e9-6d22c30938b2
Request
GET /dataServiceRest/measurements?partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}&searchCondition=4>[2015-01-01T00:00:00Z] HTTP/1.1
Response
 [
   {
     "uuid": "5b59cac7-9ecd-403c-aa26-56dd25892421",
     "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
     "lastModified": "2015-03-09T09:19:38.653Z",
     "attributes":
     {
         "4": "2015-03-09T19:12:00Z",
         "6": "3",
         "7": "0"
     }
    },
    ...
  ]

The request can be restricted by the following filter uri parameters:

Type Parameter Description
Example
UShort list requestedMeasurementAttributes
default: All attributes		 Restricts the query to the attributes that should be returned for measurements. Use an empty list {} to return no attributes.
requestedMeasurementAttributes={4,8}
None, Simple, Detailed statistics
default: None		 Indicates how statistical informtaion should be returned:
None = Return no information
Simple = Return statistical information including number of characteristics out of warning limit, number of characteristics out of tolerance and number of characteristics in warning limit and tolerance
Detailed = Return statistical information the same way as Simple plus the guid for each characteristic
statistics=Simple
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch a measurement by its guid
Request
GET /dataServiceRest/measurements/5b59cac7-9ecd-403c-aa26-56dd25892421 HTTP/1.1
Response
 [
   {
     "uuid": "5b59cac7-9ecd-403c-aa26-56dd25892421",
     "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
     "lastModified": "2015-03-09T09:19:38.653Z",
     "attributes":
     {
         "4": "2015-03-09T19:12:00Z",
         "6": "3",
         "7": "0"
     }
    }
  ]

To create a new measurement, you must send its JSON representation in the request body. A value for uuid is required, attributes and comment are optional. The attribute keys must be valid measurement attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in server settings.

Example Example: Create a measurement
Request
POST /dataServiceRest/measurements HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "3",
        "7": "0"
      }     
  }
]
Response
HTTP/1.1 201 Created

Updating a measurement is about changing measurement attributes. Pass the whole measurement including all attributes in the request body. The server then deletes all attributes and creates the new one in a single transaction.

Example Example: Update a measurement - add and change an attribute
Request
PUT /dataServiceRest/measurements HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "2",
        "7": "0",
        "8": "1"
      }
  }
]
Response
HTTP/1.1 200 OK

You have multiple options for deleting measurements measurements:

  • Delete all measurements
  • Delete measurements by their uuids
  • Delete measurements from a single part by its path
  • Delete measurements from parts by its uuids

Delete condition for deleting measurements from a single or multiple parts may be further restricted by the filter uri parameter searchCondition.

Type Parameter Description
Example
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part
partPath=/metal%20part
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be deleted.
aggregation=All
DeleteForCurrentPartOnly or DeleteDeep deep
default: DeleteForCurrentPartOnly		 Determines whether the query should delete only measurements for the given part(s) specified by either partPath or partUuids.
deep=DeleteForCurrentPartOnly
Example Example: Delete measurements newer than 01.01.2015 and older than 31.03.2015 from the part with the uuid e42c5327-6258-4c4c-b3e9-6d22c30938b2
Request
DELETE /dataServiceRest/measurements?partUuids={4b59cac7-9ecd-403c-aa26-56dd25892421}&searchCondition=4>[2015-01-01T00:00:00Z]+4<[2015-03-31T23:59:59Z] HTTP/1.1
Response
HTTP/1.1 200 OK
Example Example: Delete a measurement by its guid
Request
DELETE /dataServiceRest/measurements/5b59cac7-9ecd-403c-aa26-56dd25892421 HTTP/1.1
Response
HTTP/1.1 200 OK

You can fetch all given attribute values for a measurement attribute. Measurements to be considered are definded by the following parameters:

Type Parameter Description
Example
int key The attribute key distincted values should be fetched for
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part

partPath=/metal%20part
bool deep
default: false		 Determines whether the query should affect all levels of the inspection plan.
deep=true
OrderCriteria order
default: 4 desc		 Determines which attribute keys and which direction the keys should be ordered by
order=4 asc, 10 desc
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
DateTime fromModificationDate Specifies a date to select all measurements that where modified after that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
DateTime toModificationDate Specifies a date to select all measurements that where modified before that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
int limitResult Restricts the number of result items.
limitResult=100
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch distinced attribute values for attribute key 6 of the last 100 measurements
Request
GET /dataservicerest/distinctMeasurementAttributeValues?key=6&limitResult=100 HTTP/1.1
Response
 ["5","6","7","8","4","9","","10"]

Values

You can fetch all measurements with values or only certain measurements with values. Possible filter uri parameters are:

Type Parameter Description
Example
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part

partPath=/metal%20part
bool deep
default: false		 Determines whether the query should affect all levels of the inspection plan.
deep=true
OrderCriteria order
default: 4 desc		 Determines which attribute keys and which direction the keys should be ordered by
order=4 asc, 10 desc
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. It can be necessary to encode ‘+’ as ‘%2B’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
DateTime fromModificationDate Specifies a date to select all measurements that where modified after that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
DateTime toModificationDate Specifies a date to select all measurements that where modified before that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
int limitResult Restricts the number of result items.
limitResult=100
UShort list requestedMeasurementAttributes
default: All attributes		 Restricts the query to the attributes that should be returned for measurements. Use an empty list {} to return no attributes.
requestedMeasurementAttributes={4,8}
UShort list requestedValueAttributes
default: All attributes		 List of attributes that should be returned for values. Use an empty list {} to return no attributes.

requestedValueAttributes={1,8}
Guid list characteristicUuids Restricts the query to the characteristics for which values should be returned.
characteristicUuids={525d15c6-dc70-4ab4-bd3c-8ab2b5780e6b, 8faae7a0-d1e1-4ee2-b3a5-d4526f6ba822}
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch measurements and values newer than 01.01.2015 restricted to a certain characteristic for a part restricted by its guid
Request
GET /dataservicerest/values?partUuids={05040c4c-f0af-46b8-810e-30c0c00a379e}&searchCondition=4>[2010-11-04T00:00:00Z]&characteristicUuids={b587d548-8aa6-42b7-b292-0f3e13452c3f} HTTP/1.1
Response
 [
   {
    "characteristics":
         {
             "b587d548-8aa6-42b7-b292-0f3e13452c3f":
             {
                 "1": "-0.073420455529934786"
             }
         },
         "uuid": "88974561-a449-4a94-8b3e-970822b84406",
         "partUuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
         "lastModified": "2015-01-19T10:48:34.157Z",
         "attributes":
         {
             "4": "2010-11-05T20:30:57.6Z",
             "6": "5",
             "7": "4",
             "8": "7",
             "12": "4"
         }
    },
    ...
  ]

The request can be restricted by the following uri filter parameters: Possible filters are:

Type Parameter Description
Example
UShort list requestedMeasurementAttributes
default: All attributes		 Restricts the query to the attributes that should be returned for measurements.Use an empty list {} to return no attributes.
requestedMeasurementAttributes={4,8}
UShort list requestedValueAttributes
default: All attributes		 List of attributes that should be returned for values. Use an empty list {} to return no attributes.
requestedValueAttributes={1,8}
Guid list characteristicUuids Restricts the query to the characteristics for which values should be returned.
characteristicsUuidList={525d15c6-dc70-4ab4-bd3c-8ab2b5780e6b, 8faae7a0-d1e1-4ee2-b3a5-d4526f6ba822}
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch a measurement including all values by its guid
Request
GET /dataServiceRest/values/5b59cac7-9ecd-403c-aa26-56dd25892421 HTTP/1.1
Response
 [
   {
    "characteristics":
     {
         "b587d548-8aa6-42b7-b292-0f3e13452c3f":
         {
             "1": "-0.073420455529934786"
         },
         ...
     },
     "uuid": "5b59cac7-9ecd-403c-aa26-56dd25892421",
     "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
     "lastModified": "2015-03-09T09:19:38.653Z",
     "attributes":
     {
         "4": "2015-03-09T19:12:00Z",
         "6": "3",
         "7": "0"
     }
    },
    ...
  ]

To create a measurement with values, you must send its JSON representation in the request body. A value for uuid is required, attributes and comment are optional. The attribute keys must be valid measurement attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in server settings.

Example Example: Create a measurement with measured values
Request
POST /dataServiceRest/values HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "3",
        "7": "0"
      },
      "characteristics":
      {
         "360f55e5-77c3-49f9-9a5e-80d0a9040e2d":
         {
             "1": "0.24966522"
         },
         "b5c98235-c75c-41a4-aced-2a38c70a3866":
         {
             "1": "0.4457339"
         },
         "85bbb406-810e-4062-8a9f-c7b636cb61bd":
         {
             "1": "0.24981162"
         }
      }
  }
]
Response
HTTP/1.1 201 Created

Updating a measurement does always affect the whole measurement. This means that you must send the whole measurement, including attributes and values, in the request body. The server then deletes the old measurement and creates the new one in a single transaction.

Example Example: Update a measurement - change a measured value
Request
PUT /dataServiceRest/values HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "2",
        "7": "0",
        "8": "1"
      }
      "characteristics":
      {
         "360f55e5-77c3-49f9-9a5e-80d0a9040e2d":
         {
             "1": "0.24966522"
         },
         "b5c98235-c75c-41a4-aced-2a38c70a3866":
         {
             "1": "0.4467339"
         },
         "85bbb406-810e-4062-8a9f-c7b636cb61bd":
         {
             "1": "0.25981162"
         }
      }
  }
]
Response
HTTP/1.1 200 OK

Object Structure

Measurements do always belong to a single inspection plan part. Depending on the purpose, the measured values are included within a measurement or not. Each measurement has the following properties:

Property Description
Guid uuid Identifies the measurement uniquely.
Guid partUuid The uuid of the part the measurement belongs to.
Attribute[] attributes A set of attributes which specifies this measurement.
DateTime lastModified Contains the date and time of the last update applied to this measurement.
DataCharacteristic[] characteristics An array of the characteristics which has been measured within the measurement. Each characteristic within this array consits of the uuid it is identified by and an array of attributes which include at least the measured value attribute.
This project is maintained by Carl Zeiss Industrielle Messtechnik GmbH