# AWS::IoTEvents Construct Library

> Version 2.274.0-alpha.0

> **Separate package**
>
> `@aws-cdk/aws-iotevents-alpha` is not part of `aws-cdk-lib` — install it separately:
>
> ```sh
> npm install @aws-cdk/aws-iotevents-alpha
> pip install aws-cdk.aws-iotevents-alpha
> ```
>
> This module is [**experimental**](/stability) (alpha): its API may change in any release, without a major version bump.
---

![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)

> The APIs of higher level constructs in this module are experimental and under active development.
> They are subject to non-backward compatible changes or removal in any future version. These are
> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
> announced in the release notes. This means that while you may use them, you may need to update
> your source code when upgrading to a newer version of this package.

---

AWS IoT Events enables you to monitor your equipment or device fleets for
failures or changes in operation, and to trigger actions when such events
occur.

## `DetectorModel`

The following example creates an AWS IoT Events detector model to your stack.
The detector model need a reference to at least one AWS IoT Events input.
AWS IoT Events inputs enable the detector to get MQTT payload values from IoT Core rules.

You can define built-in actions to use a timer or set a variable, or send data to other AWS resources.
See also [@aws-cdk/aws-iotevents-actions-alpha](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-iotevents-actions-alpha-readme.html) for other actions.

```ts
import * as iotevents from '@aws-cdk/aws-iotevents-alpha';
import * as actions from '@aws-cdk/aws-iotevents-actions-alpha';
import * as lambda from 'aws-cdk-lib/aws-lambda';

declare const func: lambda.IFunction;

const input = new iotevents.Input(this, 'MyInput', {
  inputName: 'my_input', // optional
  attributeJsonPaths: ['payload.deviceId', 'payload.temperature'],
});

const warmState = new iotevents.State({
  stateName: 'warm',
  onEnter: [{
    eventName: 'test-enter-event',
    condition: iotevents.Expression.currentInput(input),
    actions: [new actions.LambdaInvokeAction(func)], // optional
  }],
  onInput: [{ // optional
    eventName: 'test-input-event',
    actions: [new actions.LambdaInvokeAction(func)],
  }],
  onExit: [{ // optional
    eventName: 'test-exit-event',
    actions: [new actions.LambdaInvokeAction(func)],
  }],
});
const coldState = new iotevents.State({
  stateName: 'cold',
});

// transit to coldState when temperature is less than 15
warmState.transitionTo(coldState, {
  eventName: 'to_coldState', // optional property, default by combining the names of the States
  when: iotevents.Expression.lt(
    iotevents.Expression.inputAttribute(input, 'payload.temperature'),
    iotevents.Expression.fromString('15'),
  ),
  executing: [new actions.LambdaInvokeAction(func)], // optional
});
// transit to warmState when temperature is greater than or equal to 15
coldState.transitionTo(warmState, {
  when: iotevents.Expression.gte(
    iotevents.Expression.inputAttribute(input, 'payload.temperature'),
    iotevents.Expression.fromString('15'),
  ),
});

new iotevents.DetectorModel(this, 'MyDetectorModel', {
  detectorModelName: 'test-detector-model', // optional
  description: 'test-detector-model-description', // optional property, default is none
  evaluationMethod: iotevents.EventEvaluation.SERIAL, // optional property, default is iotevents.EventEvaluation.BATCH
  detectorKey: 'payload.deviceId', // optional property, default is none and single detector instance will be created and all inputs will be routed to it
  initialState: warmState,
});
```

To grant permissions to put messages in the input,
you can use the `grantWrite()` method:

```ts
import * as iam from 'aws-cdk-lib/aws-iam';
import * as iotevents from '@aws-cdk/aws-iotevents-alpha';

declare const grantable: iam.IGrantable;
const input = iotevents.Input.fromInputName(this, 'MyInput', 'my_input');

input.grantWrite(grantable);
```

## Types

| Name | Kind | Summary |
| --- | --- | --- |
| [`DetectorModel`](/v2/docs/@aws-cdk_aws-iotevents-alpha.DetectorModel) | Construct (L2) | Defines an AWS IoT Events detector model in this stack. |
| [`Input`](/v2/docs/@aws-cdk_aws-iotevents-alpha.Input) | Construct (L2) | Defines an AWS IoT Events input in this stack. |
| [`ActionBindOptions`](/v2/docs/@aws-cdk_aws-iotevents-alpha.ActionBindOptions) | Struct | Options when binding a Action to a detector model. |
| [`ActionConfig`](/v2/docs/@aws-cdk_aws-iotevents-alpha.ActionConfig) | Struct | Properties for a AWS IoT Events action. |
| [`DetectorModelProps`](/v2/docs/@aws-cdk_aws-iotevents-alpha.DetectorModelProps) | Struct | Properties for defining an AWS IoT Events detector model. |
| [`Event`](/v2/docs/@aws-cdk_aws-iotevents-alpha.Event) | Struct | Specifies the actions to be performed when the condition evaluates to `true`. |
| [`EventEvaluation`](/v2/docs/@aws-cdk_aws-iotevents-alpha.EventEvaluation) | Enum | Information about the order in which events are evaluated and how actions are executed. |
| [`Expression`](/v2/docs/@aws-cdk_aws-iotevents-alpha.Expression) | Class | Expression for events in Detector Model state. |
| [`IAction`](/v2/docs/@aws-cdk_aws-iotevents-alpha.IAction) | Interface | An abstract action for DetectorModel. |
| [`IDetectorModel`](/v2/docs/@aws-cdk_aws-iotevents-alpha.IDetectorModel) | Interface | Represents an AWS IoT Events detector model. |
| [`IInput`](/v2/docs/@aws-cdk_aws-iotevents-alpha.IInput) | Interface | Represents an AWS IoT Events input. |
| [`InputProps`](/v2/docs/@aws-cdk_aws-iotevents-alpha.InputProps) | Struct | Properties for defining an AWS IoT Events input. |
| [`State`](/v2/docs/@aws-cdk_aws-iotevents-alpha.State) | Class | Defines a state of a detector. |
| [`StateProps`](/v2/docs/@aws-cdk_aws-iotevents-alpha.StateProps) | Struct | Properties for defining a state of a detector. |
| [`TransitionOptions`](/v2/docs/@aws-cdk_aws-iotevents-alpha.TransitionOptions) | Struct | Properties for options of state transition. |