Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Custom composite models (Components)

When you're modeling an especially complex industrial asset, such as a complicated piece of machinery that has many parts, it can become a challenge to keep your asset models organized and maintainable.

In such cases, you can add custom composite models, or components if you're using the console, to your existing asset models and component models. These help you stay organized by grouping related properties and re-using subcomponent definitions.

There are two types of custom composite models:

The following sections illustrate how to use custom composite models in your designs.

Inline custom composite models

Inline custom composite models provide a way to organize your asset model by grouping related properties.

For example, suppose you want to model a robot asset. The robot includes a servomotor, a power supply, and a battery. Each of those constituent parts has its own properties that you want to include in the model. You might define an asset model called robot_model that has properties such as the following.

However, in some cases, there might be many subassemblies, or the subassemblies themselves might have many properties. In these cases, there might be so many properties that they become cumbersome to reference and maintain in a single flat list at the model root, like in the preceding example.

To deal with such situations, you can use an inline custom composite model to group properties. An inline custom composite model is a custom composite model that defines its own properties. For example, you could model your robot like the following.

In the preceding example, servo, powersupply, and battery are the names of inline custom composite models defined within the robot_model asset model. Each of these composite models then defines properties of its own.

For information about how to create inline custom composite models, see Creating custom composite models (Components).

Component-model-based custom composite models

You can create a component model in Amazon IoT SiteWise to define a standard, reusable sub-assembly. Once you have created a component model, you can add references to it in your other asset models and component models. You do this by adding a component-model-based custom composite model to any model where you want to reference the component. You can add references to your component from many models, or multiple times within the same model.

In this way, you can avoid duplicating the same definitions across models. It also simplifies maintaining your models, because any changes you make to a component model will be reflected across all asset models that use it.

For example, suppose that your industrial installation has many types of equipment that all use the same kind of servo motor. Some of them have many servo motors in a single piece of equipment. You create an asset model for each equipment type, but you don't want to duplicate the definition of servo every time. You want to model it just once and use it in your various asset models. If you later make a change to the definition of servo, it will be updated across all your models and assets.

To model the robot from the previous example in this way, you could define servo motors, power supplies, and batteries as component models, like this.

You could then define asset models, such as robot_model, that reference these components. Multiple asset models can reference the same component model. You can also reference the same component model multiple times in one asset model, such as if your robot has multiple servomotors in it.

For information about how to create component models, see Creating component models.

For information about how to reference your component models in other models, see Creating custom composite models (Components).

Using paths to reference custom composite model properties

When you create a property on an asset model, component model, or custom composite model, you can reference it from other properties that use its value, such as transforms and metrics.

Amazon IoT SiteWise provides different ways for you to reference your property. The simplest way is often to use its property ID. However, if the property you want to reference is on a custom composite model, you may find it more useful to reference it by path instead.

A path is an ordered sequence of path segments that specifies a property in terms of its position among the nested composite models within an asset model and composite model.

Obtaining property paths

You can get a property's path from the path field of its AssetModelProperty.

For example, suppose you have an asset model robot_model that contains a custom composite model servo, which has a property position. If you call DescribeAssetModelCompositeModel on servo, then the position property would list a path field that looks like this:

"path": [
    {
       "id": "asset model ID",
       "name": "robot_model"
    },
    {
       "id": "composite model ID",
       "name": "servo"
    },
    {
       "id": "property ID",
       "name": "position"
    }
]

Using property paths

You can use a property path when you define a property that references other properties, such as a transform or metric.

A property uses a variable to reference another property. For more information about working with variables, see Using variables in formula expressions.

When you define a variable to reference a property, you can use either the property's ID or its path.

To define a variable that uses the path of the referenced property, specify the propertyPath field of its value.

For example, to define an asset model that has a metric that references a property by using a path, you could pass a payload like this to CreateAssetModel:

{
    ...
    "assetModelProperties": [
        {
            ...
            "type": {
                "metric": {
                    ...
                    "variables": [
                        {
                            "name": "variable name",
                            "value": {
                                "propertyPath": [
                                    path segments
                                ]
                            }
                        }
                    ],
                    ...
                }
            },
            ...
        },
        ...
    ],
    ...
}