# Custom composite models (components)
<a name="custom-composite-models"></a>

 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:
+ **Inline** custom composite models define a set of grouped properties that apply to the asset model or component model to which the custom composite model belongs. You use them to group related properties. They consists of a name, a description, and a set of asset model properties. They are not reusable.
+ **Component-model-based** custom composite models reference a component model that you want to include in your asset model or component model. You use them to include standard subassemblies in your model. They consist of a name, a description, and the ID of the component model it references. They have no properties of their own; the referenced component model provides its associated properties to any created assets.

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

**Topics**
+ [Inline custom composite models](#inline-composite-models)
+ [Component-model-based custom composite models](#component-based-custom-composite-models)
+ [Use paths to reference custom composite model properties](#property-paths)

## Inline custom composite models
<a name="inline-composite-models"></a>

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.


****  

|  | 
| --- |
|  [See the AWS documentation website for more details](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/custom-composite-models.html)  | 

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.


****  

|  | 
| --- |
|  [See the AWS documentation website for more details](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/custom-composite-models.html)  | 

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.

**Note**  
In this case, each custom composite model defines its own properties, so that all the properties are part of the asset model itself (`robot_model` in this case). These properties aren't shared with any other asset models or component models. For example, if you created some other asset model that also had an inline custom composite model called `servo`, then making a change to the `servo` within `robot_model` wouldn't affect the other asset model's `servo` definition.  
 If you want to implement such sharing (for example, to have only one definition for a servo, which all your asset models can share), you would create a component model for it instead, and then create **component-model-based** composite models that reference it. See the following section for details. 

For information about how to create inline custom composite models, see [Create custom composite models (components)](create-custom-composite-models.md).

## Component-model-based custom composite models
<a name="component-based-custom-composite-models"></a>

You can create a component model in AWS 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.


****  

|  | 
| --- |
|  [See the AWS documentation website for more details](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/custom-composite-models.html)  | 


****  

|  | 
| --- |
|  [See the AWS documentation website for more details](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/custom-composite-models.html)  | 


****  

|  | 
| --- |
|  [See the AWS documentation website for more details](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/custom-composite-models.html)  | 

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.


****  

|  | 
| --- |
|  [See the AWS documentation website for more details](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/custom-composite-models.html)  | 

For information about how to create component models, see [Create component models](create-component-models.md).

For information about how to reference your component models in other models, see [Create custom composite models (components)](create-custom-composite-models.md).

## Use paths to reference custom composite model properties
<a name="property-paths"></a>

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](transforms.md) and [metrics](metrics.md).

AWS 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.

### Obtain property paths
<a name="obtaining-property-paths"></a>

You can get a property's path from the `path` field of its [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html).

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](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModelCompositeModel.html) 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
<a name="using-property-paths"></a>

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 [Use variables in formula expressions](expression-variables.md).

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](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html):

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