Information about supported interface version can be fetched calling the root endpoint of DataService:
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.
The service information can be fetched using the following endpoint. This endpoint doesn’t provide filter parameters.
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 |
The configuration can be fetched, created, updated and deleted using the following endpoints. These endpoints do not provide filter parameters.
Creates the attribute definitions transfered within the body of the request for the given :pluralizedEntityType
which must be part of the uri
Updates the attribute definitions transfered within the body of the request for the given :pluralizedEntityType
which must be part of the uri
Deletes all attribute definitions of which the id is in the :attributeIdList
for the specified :pluralizedEntityType
. If :attributeIdList
is not specified, the request deletes all attributes of the :pluralizedEntityType
.
The PiWeb configuration consists of a list of attributes for each entity type. The different entity types are:
The attributes are either AttributeDefinition
or 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 |
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 |
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 and catalog entries can be fetched, created, updated and deleted using the following endpoints.
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).
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.
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.
Update a catalog when you want to:
To update a catalog, the whole object, excluding the valid attributes, needs to be transmitted in the body of the HTTP request. Updating a catalog essentially replaces the current catalog entries with the new one (delete followed by an add) in a single transaction.
To change the valid attributes, the catalog needs to be deleted an re-created again.
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 CatalogEntry
have the following structures:
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 |
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. |
You can fetch, create, update and delete parts and characteristics using the following endpoints:
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 depthdefault: 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 withHistorydefault: 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 requestedPartAttributesdefault: All |
Restricts the query to the attributes that should be returned for parts, for example requestedPartAttributes={1001, 1008} . |
/metal part
without child parts and only get the values for attributes 1001
and 1003
You can fetch a certain part by its :partUuid. The result can be restricted by the following uri parameters:
Parameter name | Description |
---|---|
bool withHistorydefault: 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 requestedPartAttributesdefault: All |
Restricts the query to the attributes that should be returned for parts, for example requestedPartAttributes={1001, 1008} . |
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.
The comment is only added if versioning is enabled in the server settings.
If you update a part you might want to:
If versioning is activated on the server side, every update creates a new version entry. If versioning is set to ‘Controlled by the client’ on server side it can be contolled by the following parameter:
Parameter name | Description |
---|---|
bool versioningEnableddefault: 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. |
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.
Deleting a part also deletes all its children.
You can fetch all characteristics or only the characteristics described by the uri parameters. 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 depthdefault: 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 withHistorydefault: 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 requestedCharacteristicAttributesdefault: All |
Restricts the query to the attributes that should be returned for characteristics, for example requestedCharacteristicAttributes={2001, 2101} |
You can only request direct characteristics of the part, characteristics of child parts will be ignored.
The result of fetching a certain characteristic by its :charUuid can be restricted by the following uri parameters:
Parameter name | Description |
---|---|
bool withHistorydefault: 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 requestedCharacteristicAttributesdefault: All |
Restricts the query to the attributes that should be returned for characteristics, for example requestedCharacteristicAttributes={2001, 2101} |
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.
The comment is only added if versioning is enabled in the server settings.
If you update characteristics you want to:
If versioning is activated on server side, every update of one or more characteristics creates a new version entry. If versioning is set to ‘Controlled by the client’ on server side it can be contolled by the following parameter:
Parameter name | Description |
---|---|
bool versioningEnableddefault: 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. |
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 list charUuids |
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.
Deleting a characteristic also deletes all its children.
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. |
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 |
You can fetch, create, update and delete measurements and values using the following endpoints:
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 ‘+’. 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 |
All, None, Id list requestedMeasurementAttributes default: All |
Restricts the query to the attributes that should be returned for measurements. requestedMeasurementAttributes={4,8} |
None, Simple, Detailed statistics default: None |
Indicates how statistical informtaion should be returned: None = Return no informationSimple = Return statistical information including numvber of characteristics out of warning limit, number of characteristics out of tolerance and number of characteristics in warning limit and toleranceDetailed = 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 |
The request can be restricted by the following filter uri parameters:
Type Parameter |
Description Example |
---|---|
All, None, Id list requestedMeasurementAttributes default: All |
Restricts the query to the attributes that should be returned for measurements. requestedMeasurementAttributes={4,8} |
None, Simple, Detailed statistics default: None |
Indicates how statistical informtaion should be returned: None = Return no informationSimple = Return statistical information including numvber of characteristics out of warning limit, number of characteristics out of tolerance and number of characteristics in warning limit and toleranceDetailed = 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 |
To create a new measurement, 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 measurement attributes as specified in the Configuration.
The comment is only added if versioning is enabled in server settings.
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.
You have multiple options for deleting measurements measurements:
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 |
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 ‘+’. 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 |
All, None, Id list requestedMeasurementAttributes default: All |
Restricts the query to the attributes that should be returned for measurements. requestedMeasurementAttributes={4,8} |
All, None, Id list requestedValueAttributes default: All |
List of attributes that should be returned for values. requestedValueAttributes={1,8} |
Guid list characteristicUuids |
Restricts the query to the characteristics for which values should be returned. characteristicsUuids={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 |
The request can be restricted by the following uri filter parameters: Possible filters are:
Type Parameter |
Description Example |
---|---|
All, None, Id list requestedMeasurementAttributes default: All |
Restricts the query to the attributes that should be returned for measurements. requestedMeasurementAttributes={4,8} |
All, None, Id list requestedValueAttributes default: All |
List of attributes that should be returned for values. 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 |
To create a measurement with values, 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 measurement attributes as specified in the Configuration.
The comment is only added if versioning is enabled in server settings.
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.
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. |