Asset Management Service - Developer Documentation - Developer Documentation
Skip to content

Asset Management Service

Announcement

Following endpoints of Asset Management API will have Page size restriction from 31st March'2024. The max page size limit will be changed to 200. The smaller page size will enable customer to have quicker response time and enable to bring parallelism. Kind request to adapt to this new behaviour.

Existing behaviour New behaviour
GET { { assetmgmturl } } /assets?size=2000 GET { { assetmgmturl } } / assets?size=200
GET { { assettypemgmturl } } / assettypes?size=2000 GET { { assettypemgmturl } } / assettypes?size=200
GET { { assettypemgmturl } } / aspecttypes?size=2000 GET { { assettypemgmturl } } / aspecttypes?size=200

Idea

Independent of your domain, the Asset Management Service supports you in creating digital representations of your physical assets. Such assets could be valves, engines, gas turbines, trains or buildings. The level of detail depends on your use case.

Access

For accessing this service you need to have the respective roles listed in Asset Management roles and scopes.
For accessing the Secure Data Sharing (SDS) protected APIs you need to have appropriate Policy Definitions in place. Please refer here for the list of supported APIs and Required Actions.

Basics

The API divides the functions into categories, for each category you can use a different controller. This section describes the controllers:

Aspect Types

An Aspect Type is a template for creating multiple aspects with the same variables. Aspects are a data modeling mechanism for assets. Aspects group related data points based on their logical association. An aspect can consist of several variables. You can configure, read or delete your aspect types. An aspect type is accessed by its ID. There are predefined aspect types which are available for all users, but cannot be modified or deleted.

Asset Types

An Asset Type is a pre-configured template for creating multiple assets with the same variables. Assets take on the properties of the type on which they are based. Within the type, you can define which aspects are integrated into the template. You can use a type in various assets and built several interconnections between a type and assets. You can configure, read or delete your types. An asset type is accessed by its ID. Asset Type consists of Variables and Aspects. The Variables defined on an asset type cannot be used for data ingestion so they are called as Static Variables. The Variables and Aspects are also inherited from parent Asset Types.

Basic Types

The Asset Management Service provides basic asset types for users. These are predefined asset types, which are available for all users, but cannot be modified or deleted. The available basic asset types are documented in the References for Basic Types.

Default Values

The Asset Management Service allows you to assign default values to static (non-time series) variables and static aspect types of an asset type. They are applied following a type-instance concept, so that newly created assets are automatically assigned the default values of their asset type. These values can be overwritten on instance level, if required. Refer to the Samples for Using Default Values in Asset Types to learn more about what you can do with default values.

Static Variables

Asset types consists of Static Variables and Aspects. A variable comprises of properties as name, unit, length, defaultValue, dataType and searchable. Static variables can be updated and deleted. Refer to the Samples for Updating and Deleting Asset Type Variables to learn more about updating and deleting variables.

Variable properties like name, unit, length and defaultValue can be updated however dataType and searchable cannot be updated. The changed values are propagated to all its Asset instances. Multiple variables can be updated using update variables API provided the variable names are not interchanged in same request. Updating variables is allowed to the variables defined on an asset type and not the inherited variables. The update operation will update only the given variables and other variables remain as it is. The update request should have If-Match header with value of etag fetched from the asset type. The response header contains Etag for asset type which can be used to update asset type or the variables again. There are certain validations on the update variables operation, in case of failure of a validation no any variable from the request will be updated and the request is failed. On successful update the response code is 204, in case of failure standard response codes like 400, 401, 403, 404, 412, 500 are returned along with the error message. The update variables API cannot be used to delete variables.

Variables can be deleted using asset type update API, after deleting a variable the values overridden on the Asset Instances will also be removed. Multiple variables can be deleted using asset type update API. Deleting variables is allowed only for the variables defined on the asset type and not the inherited variables.

Assets

The following types of assets are distinguished:

  • Device types: represents a machine, or any object, from which data is collected
  • Agent types: represents the agent (software or physical device) measuring and collecting data of devices, machines, etc.
  • Hierarchy types: represents the hierarchy levels of an organization
  • Application types: used by other services to collect data of their applications (e.g., Edge Analytics Application)

Using the Asset Management Service you can configure, read, manage, and assign existing files to assets. Deletion is supported for all assets, but root assets are deleted when their tenant is deleted.

Hierarchy

The Asset Management Service supports hierarchical relationships between assets. Assets inherit their parent's type assignments, but not their assets. They can overwrite the inherited type assignments. The hierarchical path of an asset from the root down via all parent assets is stored in the hierarchyPath field. This can be used as navigational aid. An example implementation of hierarchical asset relationships is provided in Modeling Hierarchical Asset Structures.

Structure

The structure of an asset can only be read, but not modified. It lists all aspects and variables without their values. You can configure the variables' values by updating the asset.

Location

You can define the location of assets and update or delete the location data.

Timezone

The timezone to be used for timeseries aggregation. By default it is inherited from the tenant's defaultTimezone, but can be overwritten only during asset creation. The timezone value should be set to a Java time zone ID such as "America/LosAngeles" or "Etc/GMT+2". Time zones that 15 or 45 minutes off a UTC hour are not supported, such as Nepal standard time (UTC+05:45). Time zones that are 30 minutes off a UTC hour are supported, such as India (UTC+05:30). Once an asset is created with a specific timezone, it cannot be changed later.

Twin Type

You can define whether an asset is the digital representation of an actual physical device (performance asset) or it is used for simulation (simulation asset).

Files

You can upload files and assign these files to assets or asset types. Each file can have multiple assignments or none at all.

Features

The Asset Management exposes its API for realizing the following tasks:

  • Create asset types as templates for assets
  • Define default values within asset types
  • Create and manage assets
  • Model complex asset structures using hierarchy
  • Upload and assign files to assets

Limitations

  • For Private Cloud, AssetTypes, AspectTypes and variables with same names but different cases should not be created. If same names are used, it may result in inconsistencies in data retrieval. For example: AspectType with name "Motor" and "motor" are treated same.

Example Scenario

A brewery has moved a conveyor belt to a different location. A fixed installed camera takes images of the conveyor belt every 2 minutes.

The Asset Management API allows you to change the location of the conveyor belt. You can define a new aspect for the conveyor belt like production volume.

Asset Attribute Calculation Guidelines and Examples

Asset Attributes

1

2

6

Asset Modelling Optimization Practices

New Models

Optimize AssetType hierarchy depth

Inheritance of AssetType from a parent type results into propagation of variable/attribute definition to child type.

3

Create Purpose Specific AssetType / AspectType

Purpose specific AssetType creation reduces the chance of unnecessary variables in Asset instances.

4

Understand the Existing “core” AssetType & AspectTypes and Use the Correct One
  • A a set of core AssetTypes which are made available to provide certain behaviour.
  • All OOTB AssetTypes have existing definitions which cannot be altered by the end-users.

5

  • Therefore, it is recommended to understand the existing type hierarchy and available variable/attribute count associated with them (both direct and inherited) before start using them.
  • An OOTB AssetType called "core.basicasset" is provided, which does not have any billable attribute. This AssetType can be used as parent AssetType to start inheritance and add purpose specific attributes through customization.
  • There are some AspectTypes variables defined with core AspectTypes for internal purpose, these variables are also excluded from billing.

Note

The minimum possible Asset Attribute count for any Asset will be 1 (even if no variables are configured in it).

Calculation of Asset Attributes and Asset Modeling guidelines

Asset attributes per asset type are calculated based on the sum of static variables in the asset type and variables in aspects associated with the asset type. If there are any attributes on the parent asset type, then the asset attributes are inherited by the child asset type. Selected asset types as parent, can have existing aspects and variables that also take part in the calculation. To know more about the aspects and variables that are taken into consideration for these asset types, refer to OOTB asset type details. The total asset attribute count is computed as the sum of asset attributes for additional asset types. For more details, refer to Calculation of Asset Attributes and Modeling Recommendation.

Disclaimer

The Asset Attribute count from the calculator may vary due to following reasons in Usage transparency.
1. Only inherited used variables from Out of the box(OOTB) asset types and aspect types are considered for calculation.
2. All other inherited unused variables from Out of the box(OOTB) asset types and aspect types; for which variable values are blank/default values and not updated/changed will be excluded from Asset Attribute calculations.
3. Calculator will assume all inherited values are used by default.

Existing Models

Remove unwanted variables/attribute definition from existing AspectType / AssetType

  • Variable definition on AssetType/AspectType gets directly counted as Asset Attribute through their Asset instances.
  • Asset Management options are provided to remove existing defined variables from AssetType & AspectType.
  • Asset Management model operations summary:
Entity Add Delete Update Updatable
Asset Supported Supported Supported - name
- description
- externalId
- parentId
- twinType
- aspects: add new aspects, remove existing aspects
- variables: add new variables, remove existing variables
- AssetLocation:country
- AssetLocation:region
- AssetLocation:locality
- AssetLocation:streetAddress
- AssetLocation:postalCode
- AssetLocation:longitude
- AssetLocation:latitude
AssetType Supported Supported Supported - name
- description
- variables []: add more variables, remove existing variables
- aspects [] : add more aspects, remove existing aspects
AssetType: aspects Supported Supported Supported - name: aspects can be renamed
AssetType: variables Supported Supported Supported - name
- unit
- length: Only for string dataType (can be increased only)
- defaultValue
AspectType Supported Supported Supported - description
- variables [] : add more variables, remove existing variables
AspectType : variables Supported Supported Supported - name
- unit
- length: Only for String dataType (can be increased only)
  • Out of all the model operations possible following operations can be used to reduce the asset attribute count:
Entity Operation Insights Hub APIs
AspectType Remove unwanted variables PATCH /aspecttypes/{id}/variables
AssetType Remove unwanted variables directly defined on AssetType PATCH /assettypes/{id} or
PUT /assettypes/{id}
AssetType Remove unwanted Aspects from AssetType PATCH /assettypes/{id} or
PUT /assettypes/{id}

Modeling Recommendation

AssetTypes are template for creating assets. For example, using a single asset type you can create number of assets. AssetType consists of multiple aspects and each aspect is defined with some variables. This association of aspects for a type defines the number of variables present for a type.

Recommendation for optimum performance

  • It is recommended, not to use more than 100 asset types overall. If 100 types are defined accurately, they are sufficient for creating 1000's of assets.
  • It is recommended, not to use more than 10 variables on a single aspect type. The sum of all the variables comprising of aspect's for a type is the total number of variables belonging to that type.
  • It is recommended, not to use more than 25 aspect types on a single asset type.
  • It is recommended, not to define more than 250 variables on a single asset type.

Examples for modelling

  • The type can be modelled with 25 aspects, each consisting of 10 variables, which will result in total 250 variables for the asset type.
  • The type can be modelled with 10 aspects, each consisting of 10 variables, which will result in total 100 variables for the type.

Note

This is not a limitation but a recommendation for optimum performance.

Modeling Recommendations for P&P Tenant

Asset Management has imposed technical limits for P&P tenant to safeguard the system and to avoid system exploitation on heavy load exceeding system limits.API rate limits for Asset Management are applicable as technical rate limits.

Following are the enforced technical limits:

Object Type Technical limit
Variable (static and dynamic) defined in an AspectType 20
Aspects associated with an AssetType 30
Static/Direct variable on a AssetType 25
Max depth in AssetType hierarchy 5
Max depth in Asset hierarchy 20
Max Attribute count per asset 500
Max Attribute count per tenant 500,000

Note

These limits are enforced on Capability Package based environments only.

Modelling recommendations (in case of error on exceeded technical limits):

Error Message Recommendation
Aspect type cannot be created as aspect type variables technical limit exceeded for tenant. Please reduce the number of variables in aspect type. 1. Reduce the number of variables in aspect type.
2. Split variables across multiple aspect types.
e.g., 30 variables on an aspect type can be split across 2 aspect types with 15 variables each.
Asset type cannot be created as asset type aspect technical limit exceeded for tenant. Please reduce the number of assettype-aspecttype associations. Reduce the number of aspects on asset type by increasing variables per aspect, but make sure that variables per aspect are within limit of 20.
Asset type cannot be created as asset type direct variable technical limit exceeded for tenant. Please reduce the number of direct variables in asset type. Reduce the number of direct variables on the asset type by shifting them over to a reusable aspect type.

API Page size Recommendation

Asset Management suggests using GET APIs in the following ways:

  • It is recommended to use the GET API with a page size of 200 via concurrent calls for faster data load and optimized performance. For example: api/assetmanagement/v3/assets?size=200.
  • Pagination can be used to get targeted asset model data. Modifying pages dynamically to show assets of interest also contributes to performance improvement.

Advantages of using GET API with page size 200

  • Faster response times when the API is called resulting in a better user experience.
  • Dynamic page loading with pagination boosts the performance of the Asset Manager.
  • Easy filtering with compact record sizes keep API transactions light.

Impact on App development

  • If the number of assets exceeds 200, multiple calls are required to obtain the complete asset model data.
  • Below APIs are eligible for page size of 200
    • api/assetmanagement/v3/assets?size=200
    • api/assetmanagement/v3/assettypes?size=200
    • api/assetmanagement/v3/aspecttypes?size=200

Transition guide for app development

  • Get the number of pages that have all the asset data. Example: api/assetmanagement/v3/assets?page=100000
  • Modify the API to start getting assets with a page size of 200. Example: api/assetmanagement/v3/assets?size=200
  • Depending on the number of pages, call the APIs concurrently to get a faster response.
  • Use pagination to get the desired result instead of skimming through the complete list of assets.

FAQs

  1. Would the requests be throttled after the first 200 records?
    No, in order to get all the records, the API should be called with different page numbers based on the total number of assets.

  2. Will there be any data loss after the first 200 records?
    There will not be any data loss after the first 200 records. You can either use pagination to use subsequent records or call the API based on different page numbers to get all the records.

  3. What is the impact of this change?
    This API limit has been set to improve the performance of the API. This allows applications to retrieve smaller data sets with better performance than processing all the records.


Last update: February 23, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.