feat(iotevents): support transition events

packages/@aws-cdk/aws-iotevents/README.md

@@ -54,13 +54,35 @@ const input = new iotevents.Input(this, 'MyInput', {
   attributeJsonPaths: ['payload.deviceId', 'payload.temperature'],
 });
 
-const onlineState = new iotevents.State({
-  stateName: 'online',
+const normalState = new iotevents.State({
+  stateName: 'normal',
   onEnter: [{
     eventName: 'test-event',
     condition: iotevents.Expression.currentInput(input),
   }],
 });
+const coldState = new iotevents.State({
+  stateName: 'cold',
+});
+
+// transit to coldState when temperature is 10
+normalState.transitionTo({
+  eventName: 'to_coldState',
+  nextState: coldState,
+  condition: iotevents.Expression.eq(
+    iotevents.Expression.inputAttribute(input, 'payload.temperature'),
+    iotevents.Expression.fromString('10'),
+  ),
+});
+// transit to normalState when temperature is 20
+coldState.transitionTo({
+  eventName: 'to_normalState',
+  nextState: normalState,
+  condition: iotevents.Expression.eq(
+    iotevents.Expression.inputAttribute(input, 'payload.temperature'),
+    iotevents.Expression.fromString('20'),
+  ),
+});
 
 new iotevents.DetectorModel(this, 'MyDetectorModel', {
   detectorModelName: 'test-detector-model', // optional

packages/@aws-cdk/aws-iotevents/lib/detector-model.ts

@@ -123,7 +123,7 @@ export class DetectorModel extends Resource implements IDetectorModel {
       key: props.detectorKey,
       detectorModelDefinition: {
         initialStateName: props.initialState.stateName,
-        states: [props.initialState._toStateJson()],
+        states: props.initialState._getStatesJson(),
       },
       roleArn: role.roleArn,
     });

packages/@aws-cdk/aws-iotevents/lib/event.ts

@@ -1,18 +1,39 @@
 import { Expression } from './expression';
+import { State } from './state';
 
 /**
- * Specifies the actions to be performed when the condition evaluates to TRUE.
+ * The base interface for events.
  */
-export interface Event {
+interface IEventBase {
   /**
    * The name of the event.
    */
   readonly eventName: string;
+}
 
+/**
+ * Specifies the actions to be performed when the condition evaluates to TRUE.
+ */
+export interface IEvent extends IEventBase {
   /**
    * The Boolean expression that, when TRUE, causes the actions to be performed.
    *
    * @default - none (the actions are always executed)
    */
   readonly condition?: Expression;
 }
+
+/**
+ * Specifies the state transition and the actions to be performed when the condition evaluates to TRUE.
+ */
+export interface ITransitionEvent extends IEventBase {
+  /**
+   * The Boolean expression that, when TRUE, causes the state transition and the actions to be performed.
+   */
+  readonly condition: Expression;
+
+  /**
+   * The next state to transit to. When the resuld of condition expression is TRUE, the state is transited.
+   */
+  readonly nextState: State;
+}

packages/@aws-cdk/aws-iotevents/lib/state.ts

@@ -1,4 +1,4 @@
-import { Event } from './event';
+import { IEvent, ITransitionEvent } from './event';
 import { CfnDetectorModel } from './iotevents.generated';
 
 /**
@@ -16,7 +16,7 @@ export interface StateProps {
    *
    * @default - events on enter will not be set
    */
-  readonly onEnter?: Event[];
+  readonly onEnter?: IEvent[];
 }
 
 /**
@@ -28,21 +28,46 @@ export class State {
    */
   public readonly stateName: string;
 
+  private transitionEvents: ITransitionEvent[] = []
+
   constructor(private readonly props: StateProps) {
     this.stateName = props.stateName;
   }
 
   /**
-   * Return the state property JSON
+   * Add a transition event to the state.
+   *
+   * @param transitionEvent the transition event that triggered if condition is evaluated to TRUE
+   */
+  public transitionTo(transitionEvent:ITransitionEvent) {
+    this.transitionEvents.push(transitionEvent);
+  }
+
+  /**
+   * Return the JSON of the states that is transited to.
+   * This function is called recursively and collect the states.
    *
    * @internal
    */
-  public _toStateJson(): CfnDetectorModel.StateProperty {
+  public _getStatesJson(states: CfnDetectorModel.StateProperty[] = []): CfnDetectorModel.StateProperty[] {
     const { stateName, onEnter } = this.props;
-    return {
+
+    if (states.some(s => s.stateName === stateName)) {
+      return states;
+    }
+
+    const newStates: CfnDetectorModel.StateProperty[] = [...states, {
       stateName,
+      onInput: {
+        transitionEvents: this.transitionEvents.length > 0 ?
+          getTransitionEventJson(this.transitionEvents) : undefined,
+      },
       onEnter: onEnter && { events: getEventJson(onEnter) },
-    };
+    }];
+
+    return this.transitionEvents.reduce((acc, transitionEvent) => {
+      return transitionEvent.nextState._getStatesJson(acc);
+    }, newStates);
   }
 
   /**
@@ -55,11 +80,20 @@ export class State {
   }
 }
 
-function getEventJson(events: Event[]): CfnDetectorModel.EventProperty[] {
+function getEventJson(events: IEvent[]): CfnDetectorModel.EventProperty[] {
   return events.map(e => {
     return {
       eventName: e.eventName,
       condition: e.condition?.evaluate(),
     };
   });
 }
+function getTransitionEventJson(events: ITransitionEvent[]): CfnDetectorModel.TransitionEventProperty[] {
+  return events.map(e => {
+    return {
+      eventName: e.eventName,
+      condition: e.condition.evaluate(),
+      nextState: e.nextState.stateName,
+    };
+  });
+}

packages/@aws-cdk/aws-iotevents/test/detector-model.test.ts

@@ -137,6 +137,63 @@ test('can set multiple events to State', () => {
   });
 });
 
+test('can set states with transitions', () => {
+  // WHEN
+  const firstState = new iotevents.State({
+    stateName: 'firstState',
+    onEnter: [{
+      eventName: 'test-eventName',
+      condition: iotevents.Expression.fromString('test-eventCondition'),
+    }],
+  });
+  const secondState = new iotevents.State({
+    stateName: 'secondState',
+  });
+
+  firstState.transitionTo({
+    eventName: 'firstToSecond',
+    nextState: secondState,
+    condition: iotevents.Expression.fromString('test-eventCondition-12'),
+  });
+  secondState.transitionTo({
+    eventName: 'secondToFirst',
+    nextState: firstState,
+    condition: iotevents.Expression.fromString('test-eventCondition-21'),
+  });
+
+  new iotevents.DetectorModel(stack, 'MyDetectorModel', {
+    initialState: firstState,
+  });
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::IoTEvents::DetectorModel', {
+    DetectorModelDefinition: {
+      States: [
+        {
+          StateName: 'firstState',
+          OnInput: {
+            TransitionEvents: [{
+              EventName: 'firstToSecond',
+              NextState: 'secondState',
+              Condition: 'test-eventCondition-12',
+            }],
+          },
+        },
+        {
+          StateName: 'secondState',
+          OnInput: {
+            TransitionEvents: [{
+              EventName: 'secondToFirst',
+              NextState: 'firstState',
+              Condition: 'test-eventCondition-21',
+            }],
+          },
+        },
+      ],
+    },
+  });
+});
+
 test('can set role', () => {
   // WHEN
   const role = iam.Role.fromRoleArn(stack, 'test-role', 'arn:aws:iam::123456789012:role/ForTest');

packages/@aws-cdk/aws-iotevents/test/integ.detector-model.expected.json

@@ -37,7 +37,7 @@
       "Type": "AWS::IoTEvents::DetectorModel",
       "Properties": {
         "DetectorModelDefinition": {
-          "InitialStateName": "online",
+          "InitialStateName": "firstState",
           "States": [
             {
               "OnEnter": {
@@ -63,7 +63,50 @@
                   }
                 ]
               },
-              "StateName": "online"
+              "OnInput": {
+                "TransitionEvents": [
+                  {
+                    "Condition": {
+                      "Fn::Join": [
+                        "",
+                        [
+                          "$input.",
+                          {
+                            "Ref": "MyInput08947B23"
+                          },
+                          ".payload.temperature == 12"
+                        ]
+                      ]
+                    },
+                    "EventName": "firstToSecond",
+                    "NextState": "secondState"
+                  }
+                ]
+              },
+              "StateName": "firstState"
+            },
+            {
+              "OnInput": {
+                "TransitionEvents": [
+                  {
+                    "Condition": {
+                      "Fn::Join": [
+                        "",
+                        [
+                          "$input.",
+                          {
+                            "Ref": "MyInput08947B23"
+                          },
+                          ".payload.temperature == 21"
+                        ]
+                      ]
+                    },
+                    "EventName": "secondToFirst",
+                    "NextState": "firstState"
+                  }
+                ]
+              },
+              "StateName": "secondState"
             }
           ]
         },

packages/@aws-cdk/aws-iotevents/test/integ.detector-model.ts

@@ -10,8 +10,8 @@ class TestStack extends cdk.Stack {
       attributeJsonPaths: ['payload.deviceId', 'payload.temperature'],
     });
 
-    const onlineState = new iotevents.State({
-      stateName: 'online',
+    const firstState = new iotevents.State({
+      stateName: 'firstState',
       onEnter: [{
         eventName: 'test-event',
         // meaning `condition: 'currentInput("test_input") && $input.test_input.payload.temperature == 31.5'`
@@ -24,13 +24,35 @@ class TestStack extends cdk.Stack {
         ),
       }],
     });
+    const secondState = new iotevents.State({
+      stateName: 'secondState',
+    });
+
+    // 1st => 2nd
+    firstState.transitionTo({
+      eventName: 'firstToSecond',
+      nextState: secondState,
+      condition: iotevents.Expression.eq(
+        iotevents.Expression.inputAttribute(input, 'payload.temperature'),
+        iotevents.Expression.fromString('12'),
+      ),
+    });
+    // 2st => 1st
+    secondState.transitionTo({
+      eventName: 'secondToFirst',
+      nextState: firstState,
+      condition: iotevents.Expression.eq(
+        iotevents.Expression.inputAttribute(input, 'payload.temperature'),
+        iotevents.Expression.fromString('21'),
+      ),
+    });
 
     new iotevents.DetectorModel(this, 'MyDetectorModel', {
       detectorModelName: 'test-detector-model',
       description: 'test-detector-model-description',
       evaluationMethod: iotevents.EventEvaluation.SERIAL,
       detectorKey: 'payload.deviceId',
-      initialState: onlineState,
+      initialState: firstState,
     });
   }
 }