Watson IoT Action Manager Concepts & API Overview

IBM Watson Internet of Things
IBM Watson IoT Platform
Action Manager Concepts &
API Overview
Version 1.0

Agenda
•Overview
•Resources
– Actions
– Triggers
•Actions API Overview
•Triggers API Overview
•Processing Walkthrough

Overview
•The Action Manager is a general purpose component that can invoke actions when
events occur within the platform
•Examples of events that could trigger actions:
– Embedded rule fires
– Device/Thing State update (future)
– Configuration change (future)
•Examples of the types of Action that could be supported:
– Webhook
– Email (future)
– MQTT (future)
– etc…

Resources – Actions
• An action represents the action to be performed, i.e.:
– Invoke a webhook
– Send an email
– Publish an MQTT event
– Etc..
• The Action resource:
– Encapsulates all of the metadata required to perform the
action
– Is intended to be agnostic of how it is invoked
v Allows different triggers to be defined for the same action
– Defines a common set of metadata
v Name
v Id
v Description
v Type
v Configuration
v Enabled
v Etc…
Action
{
"id": "5848040f6522050001db0e20",
"name" : "My Webhook Action",
"description" : "An example webhook action",
"type": "webhook",
"enabled": true,
"configuration": {
…
},
"adminDisabled": false,
"adminDisabledReason": null,
"created": "2018-01-30T13:00:00Z",
"createdBy": "john.doe@us.ibm.com",
"updated": "2018-01-30T14:00:00Z",
"updatedBy": "fred.bloggs@uk.ibm.com",
"refs": {
"triggers": " /api/v0002/actions/5848040f6522050001db0e20/triggers"
}
}

•The Action resource is polymorphic
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

•The type of the action is defined by the type
property
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

•The type of the action is defined by the type
property
•The value of the configuration property varies
depending on the type of the action
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

Resources – Webhook Actions
•A Webhook Action is used to invoke a webhook
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"targetUrl": "http://webhook-sim/abcdef/senddata",
"method": "POST",
"contentType": "application/json",
"username": "john.doe@us.ibm.com",
"password": "passw0rd",
"headers": [
{
"name": "mycustomheader",
"value": "{{somevalue}}"
}
],
"body": "{"id" : {{theId}}, "data": "{{theData}}"}"
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}
Webhook
Action

•The configuration property must define the
following properties:
– targetUrl
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}
Webhook
Action

– targetUrl
•It can also define the following optional
properties:
– method (defaults to POST)
– contentType (defaults to application/json)
– username
– password
– headers (defaults to empty array)
– body (defaults to empty string)
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}
Webhook
Action

Resources – EMail Actions (future)
•An EMail Action is used to send an email
Action
{
"id": "5848040f6522050001db0e20",
"type": "email",
"enabled": true,
"configuration": {
"host": "smtp.gmail.com",
"port": 587,
"to": [
"jane.doe@us.ibm.com",
],
"cc": [],
"bcc": [],
"subject": "{{alertType}} alert from the WIoTP Platform"
"content": "The state has changed {{state}}",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}
Email
Action

– host
– port
– username
– password
– to
Action
{
"id": "5848040f6522050001db0e20",
"type": "email",
"enabled": true,
"configuration": {
"port": 587,
"to": [
],
"cc": [],
"bcc": [],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}
Email
Action

– host
– port
– username
– password
– to
•It can also define the following optional
properties:
– subject (defaults to empty string)
– content (defaults to empty string)
– cc (defaults to empty array)
– bcc (defaults to empty array)
Action
{
"id": "5848040f6522050001db0e20",
"type": "email",
"enabled": true,
"configuration": {
"port": 587,
"to": [
],
"cc": [],
"bcc": [],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}
Email
Action

Resources – Action Variables
•The properties defined on the configuration
object can also include variables
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

•Variables are defined using Mustache syntax
http://mustache.github.io/mustache.5.html
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

•Variables are defined using Mustache syntax
http://mustache.github.io/mustache.5.html
•An action can define a maximum of 32 unique
variables
•The values of the variables are defined by the
triggers for the action (more on this later)
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

•The following features of Mustache are
supported:
– Variables
{{myVariable}}
– Sections
{{#mySection}}
Hello {{name}}
{{/mySection}}
– Inverted Sections
{{^myInvertedSection}}
No name specified!!!
{{/myInvertedSection}}
– Comments
{{! A Comment}}
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

•The following features of Mustache are not
supported:
– Partials
{{> myPartial}}
– Lambdas
– Setting delimiters
{{=<% %>=}}
<% erb_style_tags %>
<%={{ }}=%>
Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

Resources – Triggers
•In order for an action to be invoked, you need to
define at least one trigger for the action
– Triggers are a sub-resource of an Action in the REST
resource hierarchy
•A trigger:
– Maps an internal event within the platform onto
the target action
– Defines a common set of metadata
v Name
v Id
v Description
v Type
v VariableMappings
v Configuration
v Enabled
v Etc…
Trigger
{
"id": "5848040f6522050001db0e20",
"name" : "My Rule Trigger",
"description" : "An example rule trigger",
"type": "rule",
"enabled": true,
"variableMappings": {
"someValue": "myHeaderValue",
"theId": "$event.state.equipmentId",
"theData": "$event.state.temperatureReading"
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"updatedBy": "fred.bloggs@uk.ibm.com"
}

•The Trigger resource is polymorphic
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

•The type of the trigger is defined by the type
property
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

•The type of the trigger is defined by the type
property
•The value of the configuration property varies
depending on the type of the trigger
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

Resources – Rule Triggers
•A Rule Trigger invokes an Action when an
embedded rule fires
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"logicalInterfaceId": "123456789012345678901234",
"ruleId": "098765432109876543210987",
"type": "device",
"typeId": "TempSensor",
"instanceId": "ts001"
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
Rule
Trigger

Resources – Rule Triggers
•A Rule Trigger invokes an Action when an
embedded rule fires
– logicalInterfaceId
– ruleId
v A wildcard (*) can be specified for the ruleId property
v Specifies that the action will be invoked if any of the
rule on the logical interface fire
– type
v One of device, thing or *
– typeId
v The id of the device or thing type or *
– instanceId
v The id of the device or thing or *
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
Rule
Trigger

Resources – State Triggers (future)
•A State Trigger invokes an Action when the state
of a Device/Thing changes
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "state",
"enabled": true,
},
"configuration": {
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
State
Trigger

Resources – State Triggers (future)
•A State Trigger invokes an Action when the state
of a Device/Thing changes
– logicalInterfaceId
– type
v One of device, thing or *
– typeId
v The id of the device or thing type or *
– instanceId
v The id of the device or thing or *
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "state",
"enabled": true,
},
"configuration": {
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
State
Trigger

Resources – Trigger Variable Mappings
•The variable mappings defined by a Trigger specify
how to map data from the platform event to the
variables required by the action
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

•The keys are the names of the variables defined in
the action configuration
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

•The keys are the names of the variables defined in
the action configuration
•The values are JSONata expressions
Trigger
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
…
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

Actions API Overview
•CRUD operations can be performed against the actions resource using the
APIs shown below
•NOTE: The actions resource does not follow the draft/active model used by
other IM resources. You do not need to activate changes in order for them
to be effective.
POST /actions
PUT /actions/{actionId}
DELETE /actions/{actionId}
GET /actions
GET /actions/{actionId}
PATCH /actions/{actionId}

Creating an Action Resource
• In order to create an action you need to perform a HTTP
POST against the /actions resource, as shown below:
• NOTE:
For security reasons, the username and password properties
are obfuscated in the responses to the REST API calls
Action
POST /actions
{
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [ {"name": "mycustomheader", "value": "{{somevalue}}"} ],
}
}

Triggers API Overview
•CRUD operations can be performed against the triggers resource using the
APIs shown below
•NOTE: The triggers resource does not follow the draft/active model used by
other IM resources. You do not need to activate changes in order for them
to be effective.
POST /triggers
PUT /triggers/{triggerId}
DELETE /triggers/{triggerId}
GET /triggers
GET /triggers/{triggerId}

Creating a Trigger Resource
• Once an action has been created in the Platform, the
next step is to create a trigger resource
– Triggers are a sub-resource of an action in the REST
resource hierarchy
• In order to create a trigger you need to perform a HTTP
POST against the /actions/{actionId}/triggers resource,
as shown below:
Action
POST /actions/{actionId}/triggers
{
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
}
}
Trigger

Action-Mgr Service Processing Walkthrough
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
…
}
Rule Trigger Webhook Action
•A rule trigger and webhook action have been created within the platform

{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
…
}
{
"type": "device",
"typeId" : "TempSensor",
"instanceId" : "ts001",
"ruleId": "098765432109876543210987",
"ruleCondition": "$state.temperature > 40",
"state": {
"equipmentId": "12345",
"temperatureReading": 45
},
"updated": "2018-01-30T14:00:00Z",
}
Rule Event Rule Trigger Webhook Action
•When a rule fires…

{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
…
}
{
"type": "device",
"ruleId": "098765432109876543210987",
"state": {
},
"updated": "2018-01-30T14:00:00Z",
}
Rule Event Rule Trigger Webhook Action
•When a rule fires…
•… the Action Manager checks to see if there is a matching rule trigger

{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
{
"type": "device",
"ruleId": "098765432109876543210987",
"state": {
},
"updated": "2018-01-30T14:00:00Z",
}
Rule Event Rule Trigger
{
"someValue": "myHeaderValue"
}
Variable Dictionary
•Having found a matching trigger, the Action Manager evaluates the variable
mappings to create the variable dictionary
•The first variable mapping (someValue) simply contains a constant value, so
this is added to the dictionary

{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
{
"type": "device",
"ruleId": "098765432109876543210987",
"state": {
},
"updated": "2018-01-30T14:00:00Z",
}
{
"theId": "12345"
}
Variable Dictionary
•The second variable mapping (theId) is assigned the value of the
state.equipmentId property from the rule notification event

{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}
{
"type": "device",
"ruleId": "098765432109876543210987",
"state": {
},
"updated": "2018-01-30T14:00:00Z",
}
{
"theId": "12345",
"theData": "45"
}
Variable Dictionary
•The third variable mapping (theData) is assigned the value of the
state.temperatureReading property from the rule notification event

{
"theId": "12345",
"theData": "45"
}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
…
}
Webhook Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
"value": "myHeaderValue"
}
],
},
…
}
Variable Dictionary Resolved Action
•Having created the variable dictionary, the Action Manager substitutes the
variables in the action with the corresponding values from the dictionary
•The variable someValue is replaced with the value myHeaderValue

{
"theId": "12345",
"theData": "45"
}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
…
}
Webhook Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
"body": "{"id" : 12345, "data": "{{theData}}"}"
},
…
}
•The variable theId is replaced with the value 12345

{
"theId": "12345",
"theData": "45"
}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
},
…
}
Webhook Action
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
"body": "{"id" : 12345, "data": "45"}"
},
…
}
•The variable theData is replaced with the value 45

{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
"headers": [
{
}
],
"body": "{"id" : 12345, "data": "45"}"
},
…
}
Resolved Action
Watson IoT Platform
Action Manager
Device
Gateway
& Edge
Cognitive
Engine
Application
UI
Device
Device
Webhook
•Once all of the variables in the action have been
processed, the resolved action is used to invoke
the target webhook

Backup

• Retrieve the list of actions that have been defined for an organization in the Watson IoT
Platform
• The following query parameters are supported:
– _bookmark, _limit, _sort, name, type and enabled
{
"results": [ {
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
} ],
"meta": {
"facets":{},
"total_rows": 1
}
}
GET /actions

POST /actions
• Creates a new action for an organization in the Watson IoT Platform
• Example POST:
{
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
}
}

POST /actions
• Example response body:
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

• Retrieve the metadata for a specific action
GET /actions/{actionId}
{
"id": "5848040f6522050001db0e20",
"type": "webhook",
"enabled": true,
"configuration": {
"method": "POST",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
"refs": {
}
}

• Perform an operation against the specified action
• Current supported operations are:
– invoke-action
• Example PATCH:
{
"operation": "invoke-action"
"variables": {
"theId": "12345",
"theData": "45"
}
}

{
"message": "CUDAM0900I: The action 'Invoke Webhook Sim Action' was successfully invoked.",
"details": {
"id": "CUDAM0900I",
"properties": ["Invoke Webhook Sim Action"]
},
"result": {
"actionId": "5c52ec190ec83c004d8e02f1",
"successful": true,
"type": "webhook",
"status": 200,
"headers": {
"connection": "keep-alive",
"content-type": "text/html; charset=utf-8",
"Content-Length": "20",
"Date": "Thu, 31 Jan 2019 12:37:46 GMT",
"X-Powered-By": "Express"
},
"contentType": "text/html; charset=utf-8",
"body": "{ "success" : true }"
}
}

• Update the metadata for an action
• The following metadata properties can be updated
– name
– description
– configuration
– enabled
PUT /actions/{actionId}
• Delete an action
DELETE /actions/{actionId}

• Retrieve the list of triggers that have been defined for an action
• The following query parameters are supported:
– _bookmark, _limit, _sort, name, type and enabled
{
"results": [ {
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
} ],
"meta": {
"facets": {},
"total_rows": 1
}
}
GET /actions/{actionId}/triggers

• Creates a new trigger for an action
• Example POST:
{
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
}
}

{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

• Retrieve the metadata for a specific trigger
GET /actions/{actionId}/triggers/{triggerId}
{
"id": "5848040f6522050001db0e20",
"type": "rule",
"enabled": true,
},
"configuration": {
"ruleId": "098765432109876543210987",
"type": "device",
},
"created": "2018-01-30T13:00:00Z",
"updated": "2018-01-30T14:00:00Z",
}

• Update the metadata for a trigger
• The following metadata properties can be updated
– name
– description
– configuration
– variableMappings
– enabled
PUT /actions/{actionId}/triggers/{triggerId}
• Delete a trigger
DELETE /actions/{actionId}/triggers/{triggerId}

Watson IoT Action Manager Concepts & API Overview

Recommended

Recommended

More Related Content

Similar to Watson IoT Action Manager Concepts & API Overview

Similar to Watson IoT Action Manager Concepts & API Overview (20)

Recently uploaded

Recently uploaded (20)

Watson IoT Action Manager Concepts & API Overview