Data Objects

Generic data object storage

In principle, each application is based on a set of specific Data Objects that are related to each other, have specific functions and are usually persisted.

AOP provides basic functions for managing such objects and takes on the role of an easy-to-use object database. The storage handling and organization remains hidden to the user, who just uses the API to access all Data Objects in a uniform manner.

Type

The type defines which concrete Properties an Object of this type can have and what their meaning is. The type is identified by a string id like “datapoint” or “location” which has to be unique within the AOP application.

Properties

Every Data Object has a Property “Id” which uniquely identifies the Object.

Beside this the Data Object may have the following common Properties:

Property	Type	Description
Id	guid	(Mandatory) Unique identifier of the Data Object, usually set by AOP on create.
ParentId	guid	Id of the Data Objects parent (if appropriate).
EditUser	string	(Readonly) Id of the user who last modified the Object, set by AOP.
EditTime	time	(Readonly) Time of the last user modification, set by AOP.

Services

All Data Objects can be read generically through the Generic Data Service.

For most Data Objects there is also a specific service available with the name of the object type, described below as an example for the object type SampleType.

The Get() function, which can also be used for paginated access, is described in more detail below (→ Get).

When writing an object (Create, Update or BulkModify), a different type is used (SampleTypeRaw), that only contains the raw properties that can be changed and persisted (see Effective/Raw Properties).

Functions

Result	Name / Params			Comment
SampleTypeGetResult	sampletype.Get			Returns a filtered list of SampleType Objects.
		mode	string	(Optional) View of the objects to return: raw or effective. Default is effective. See DataMode.
		include	string	(Optional) Adds the other view to the result; only values that differ are added (under @meta.overlay). See DataMode.
		filter	DataFilter	(Optional) Filter definition which determines the result set.
		sort	DataSortItem[]	(Optional) Sorting definition as a list of properties with order.
		offset	int	(Optional) Offset of the first Object in the result set that should be returned. Used for direct pagination.
		limit	int	(Optional) Maximum amount of Objects that should be returned. (Max : 100000)
		select	string[]	(Optional) List of properties that should be contained in the result objects.
SampleTypeGetResult	sampletype.GetNext			Returns a filtered list of SampleType Objects as a follow up to a previous Get call.
		context	string	The context received within the last get result. Mandatory for subsequent get calls with pagination.
		scroll	int	(Optional) Scrolls through the result set with 'Next' or 'Prev'. Used for pagination. See PaginationScroll.
		offset	int	(Optional) Offset of the first Object in the result set that should be returned. Used for direct pagination.
		limit	int	(Optional) Maximum amount of Objects that should be returned. (Max : 100000)
SampleType	sampletype.GetOne			Returns a single SampleType Object identified by the given id.
		id	guid	The SampleType's id.
		mode	string	(Optional) View of the object to return: raw or effective. Default is effective. See DataMode.
		include	string	(Optional) Adds the other view to the result; only values that differ are added (under @meta.overlay). See DataMode.
		select	string[]	(Optional) List of properties that should be contained in the result object.
guid	sampletype.Create			Creates the SampleType in the system and returns the id of the SampleType. The SampleType must not have an id. If an id is set, the creation is rejected and an empty id is returned.
guid		object	SampleTypeRaw	The SampleType to create.
bool	sampletype.Update			Updates a SampleType with data from the provided Object.
		id	guid	Id of the SampleType to update.
		object	SampleTypeRaw	SampleType to update
bool	sampletype.Set			Sets specific properties of a SampleType Object.
		id	guid	Id of the SampleType to modify.
		props	value{}	(Key: SymbolPath) List of properties that should be set. Property paths may be used as ids to address any partial aspect of the Object.
bool	sampletype.Delete			Deletes a SampleType Object. Returns true if successfully deleted or if no such Object existed to begin with.
bool		id	guid	Id of the SampleType to delete.
bool	sampletype.BulkModify			Performs a bulk of changes at once.
		create	SampleTypeRaw[]	(Optional) List of SampleType Objects to create.
		update	SampleTypeRaw[]	(Optional) List of SampleType Objects to update.
		set	ObjectAspect[]	(Optional) List of SampleType Object properties to set.
		delete	guid[]	(Optional) List of SampleType ids to delete.

Notifications

Name / Params			Comment
sampletype.Created			Notifies about new SampleType Objects.
	objects	SampleType[]	Newly created SampleType Objects.
sampletype.Updated			Notifies about updated SampleType Objects.
	objects	SampleType[]	Changed SampleType Objects.
sampletype.Deleted			Notifies about deleted SampleType Objects.
	ids	guid[]	Ids of the deleted SampleType Objects.

Objects

SampleType

Property	Type	Description
Id	guid	(Unique)
EditTime	time	(Readonly, Not in default set)
EditUser	string	(Readonly, Not in default set)

SampleTypeRaw

Property	Type	Description
Id	guid	(Unique)

GetResult

Property	Type	Description
Objects	value[]	Array of Objects.
Pagination	Pagination	Describes the result set, if not all Objects were returned.

Pagination

Property	Type	Description
TotalCount	int	(DistinctNull) Total count of available Objects, if available.
Offset	int	(DistinctNull) Offset of first Object, if available.
Count	int	Count of returned Objects.
Context	string	Pagination context for subsequent get calls. The content depends on the service and should be seen as opaque.
HasNext	bool	Can request next Objects for context.
HasPrev	bool	Can request previous Objects for context.

PaginationScroll

Name	Value	Description
Offset	0	Scrolls to fixed position.
Next	1	Scrolls to next items for given context.
Prev	2	Scrolls to previous items for given context.

DataMode

Name	Value	Description
Effective	effective	Resolved values (default).
Raw	raw	Persisted values.

DataFilter

Property	Type	Description
FilterId	string	DataForm id which defined the filter. For realization of special filter behaviour.
SearchText	string	Text to search for.
SearchIn	string[]	List of properties that will be searched for the text.
Props	value{}	List of object properties with accepted values. All properties must match.
Expression	string	Free condition that matching objects must satisfy.

DataSortItem

Property	Type	Description
Property	string	Property to be sorted by.
Order	int	Sort order. See DataSortOrder.

DataSortOrder

Name	Value	Description
Default	0	Default sort order.
Ascending	1	Sort ascending.
Descending	2	Sort descending.

ObjectAspect

Property	Type	Description
Id	string	Id of the Object. May be a guid (as string) or string id.
Props	value{}	List of properties to change. Property paths may be used to address any partial aspect of the Object.

SampleTypeGetResult

Property	Type	Description
Objects	SampleType[]	Array of Objects.
Pagination	Pagination	Describes the result set, if not all Objects were returned.

Get

The Get function is used for the initial data request. In case the results are paginated, subsequent requests are to be made with the GetNext function.

With the optional parameters, you can

Control whether the returned objects’ properties should be effective, raw or both (see Effective/Raw Properties).
Set a Filter.
Select which properties the returned objects should contain.
Limit the number of results.

Effective/Raw Properties

Some data types contain so-called effective properties that can differ from the raw, persisted values because of inheritance or a runtime component. If a datapoint’s persisted category has not been set for example, its effective category can contain the parent datapoint’s category or a datapoint pattern’s category. If a property is localizable, its effective values are also translated in the connection’s language if a language has been set via SetLanguage.

When querying data objects, the mode parameter controls whether to retrieve the raw, persisted values or the effective values. By default, for those properties that can contain effective values, the effective values are returned. If you want to retrieve both raw and effective values together, you can set the include parameter to raw in conjunction with the mode parameter set to effective. This will return the object with effective values but also contain a “@meta” property consisting of an “overlay” property that contains the raw values of all properties that differ from the effective values.

Example:
{
  "Id": "0815",
  "Name": "Ok",
  "Symbol": {
    "Color": "Red"
  },
  "@meta": {
    "overlay": [
      { "Name": "[dict.ok]" },
      { "Symbol.Color": "[dict.red]" }
    ]
  }
}

Pagination

If there are more Objects available than can be returned with one call, the result set will be paginated. In this case, a Pagination object will be returned by GetResult which contains a Context. This Context is required for subsequent calls to the GetNext function.

Pagination principially supports two modes Scrolling and Direct Page Access, but not all object types support both modes.

Scrolling

If Scrolling is possible, either HasNext or HasPrev are set in the Pagination object, and consecutive calls are given that Context together with the desired Scroll direction. The Limit specifies the amount of objects which should be returned in that direction.

Direct Page Access

Direct page access is possible if the Pagination object contains TotalCount and Offset. In that case you can directly move to a desired page by calculating its Offset and handing it over together with the Context. Offset and Scroll should never be used together.

Limit

The Limit ist not stored in the Context, so this parameter should always be added if the amount of Objects in the result set should be limited. This Limit can not exceed 100000. If no Limit is given the maximum of 100000 is used by default.

Filter

To query only certain Objects, the filter param can be used in different ways.

“SearchText” and “SearchIn” allow you to match a text string within a certain set of properties.
“Props” allows you to supply a list of key value pairs. The object’s properties of the same name must match all of these values exactly.
“Expression” allows you to supply an Expression string. All property ids of the respective object type can be used as a variable in that expression, and also Property Paths may be used.

If you supply multiple properties in the filter, all of them must match (logical AND).

Select

The select parameter is a string[] which contains all Property Ids which the result object should contain. For ease of use, the following special selectors can be used:

Select Id	Description
[default]	Select the default Property set.
[all]	Select all available Properties.

Especially [default] is helpful, because it allows specifying specific additional Properties to be returned in addition to the default set.

Create

Even though SampleObjectRaw has an id property it must not be set when calling the Create function or for creates in BulkModify. It is merely used to identify the existing object for updates in BulkModify.

Last modified September 25, 2026