In Platform Service, an action can be used to automatically perform tasks or operations in response to notifications generated by the Platform Service. For example, you can define an action that sends an alert to the dashboard on a user's device in response to a rule notification.
Actions are made up from two resources that you configure by using the REST API:
name, type and configuration properties.
The type of the action is defined by the type property. At present, the Platform Service only supports actions of type webhook. The configuration property can include a number of variables that allow you to
substitute data from the triggering event before the action is invoked. For more information, see the Using variables section.type and configuration properties. The type of the trigger is defined by the type property. At present, the Platform Service only supports triggers of type rule. A trigger also includes mappings for all of the variables that are defined on the
associated action.Action resources are created using the REST API.
Use the POST /actions API call to create an action resource. Include the action name, type and configuration properties:
{
"name" : "My Webhook Action",
"description" : "An example webhook action",
"type": "webhook",
"enabled": true,
"configuration": {
"targetUrl": "http://webhook-sim/{{someId}}/senddata",
"method": "POST",
"contentType": "application/json",
"username": "john.doe@us.ibm.com",
"password": "passw0rd",
"headers": [
{
"name" : "mycustomheader",
"value" : "{{somevalue}}"
},
{
"name" : "{{deviceIntHeader}}",
"value" : "{{intValue}}"
},
{
"name" : "From",
"value" : "john.doe@us.ibm.com"
}
],
"body" : "{\"specialIntValue\" : {{someInt}}, \"someStringValue\": \"{{someString}}\"}"
}
}
Some of the properties defined on the configuration object include variables, for example, {{someValue}}. Variables are defined using Mustache syntax. A corresponding variable mapping for each variable must be defined on
any triggers that are associated with an action. See Supported mustache features for more information. The following example shows the response to the POST method:
{
"id": "5cbf508ff07686001ff778de",
"name" : "My Webhook Action",
"description" : "An example webhook action",
"type": "webhook",
"enabled": true,
"adminDisabled": false,
"created": "2018-01-31T10:23:26Z",
"createdBy": "a-7p9t2v-zsrcacabpa",
"updated": "2018-01-31T10:23:26Z",
"updatedBy": "a-7p9t2v-zsrcacabpa",
"configuration": {
"targetUrl": "http://webhook-sim/{{someId}}/senddata",
"method": "POST",
"contentType": "application/json",
"username": "john.doe@us.ibm.com",
"password": "passw0rd",
"headers": [
{
"name" : "mycustomheader",
"value" : "{{somevalue}}"
},
{
"name" : "{{deviceIntHeader}}",
"value" : "{{intValue}}"
},
{
"name" : "From",
"value" : "john.doe@us.ibm.com"
}
],
"body" : "{\"specialIntValue\" : {{someInt}}, \"someStringValue\": \"{{someString}}\"}"
},
"refs": {
"triggers": "/api/v0002/actions/5cbf508ff07686001ff778de/triggers"
}
}
You can use the PATCH /actions/{actionId} API call to test your action.
You must include the operation and variables properties in the body content:
{
"operation": "invoke-action",
"variables": {
"someId": "bob",
"somevalue": "oranges",
"deviceIntHeader": "device-version",
"intValue": 2,
"someInt": 42,
"someString": "apples"
}
}
Important: The variables property must define a value for each variable that is included in the action resource. For more information, see the Using variables section.
The following example
shows the response to the POST method:
{
"message": "CUDAM0900I: The action 'My Webhook Action' was successfully invoked.",
"details": {
"id": "CUDAM0900I",
"properties": [
"My Webhook Action"
]
},
"result": {
"actionId": "5cbf508ff07686001ff778de",
"successful": true,
"type": "webhook",
"status": 202,
"headers": {
"Server": "cloudflare",
"CF-RAY": "4e6cfa739df5c7f6-DFW",
"X-Request-ID": "4bc579852f954cf33637e9a6ce5a370c",
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, DELETE, POST, PUT, HEAD",
"x-openwhisk-activation-id": "3346c5a39243427b86c5a39243327b70",
"Connection": "keep-alive",
"Date": "Fri, 14 Jun 2019 14:26:16 GMT",
"Access-Control-Allow-Headers": "Authorization, Origin, X-Requested-With, Content-Type, Accept, User-Agent",
"IBM_Cloud_Functions": "OpenWhisk",
"Set-Cookie": "__cfduid=df3777275e6a0123456789012345678901234567890; expires=Sat, 13-Jun-20 14:26:16 GMT; path=/; domain=.functions.cloud.ibm.com; HttpOnly",
"Content-Length": "51",
"Content-Type": "application/json",
"Expect-CT": "max-age=604800, report-uri=\"https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct\""
},
"contentType": "application/json",
"body": "{\"activationId\":\"3346c5a39243427b86c5a39243327b70\"}"
}
}
Trigger resources are created using the REST API. Multiple triggers can be associated with an action.
name, type configuration and variableMappings properties: {
"name": "My Trigger",
"description": "An example webhook action",
"type": "rule",
"enabled": true,
"configuration": {
"logicalInterfaceId": "5846ed076522050001db0e12",
"ruleId": "*",
"type": "*",
"typeId": "*",
"instanceId": "*"
},
"variableMappings": {
"someId": "$event.instanceId",
"somevalue": "$event.logicalInterfaceId",
"deviceIntHeader": "'device-version'",
"intValue": "$event.state.version",
"someInt": "$event.state.temperature * 2",
"someString": "$event.ruleId"
}
}
variableMappings property must include a mapping for each variable that is defined on the associated action. For a rule trigger, the configuration property must include the logicalInterfaceId,
ruleId, type, typeId and instanceId properties. The value of the logicalInterfaceId property must be the identifier of the logical interface that the relevant rule is associated with.
It cannot have a wildcard value, *. All of the other configuration properties can have a wildcard value, as shown in the example. For information about how to locate the IDs, see Creating embedded rules. {
"name": "My Trigger",
"description": "An example webhook action",
"type": "rule",
"enabled": true,
"adminDisabled": false,
"created": "2018-01-31T10:23:26Z",
"createdBy": "a-7p9t2v-zsrcacabpa",
"updated": "2018-01-31T10:23:26Z",
"updatedBy": "a-7p9t2v-zsrcacabpa",
"configuration": {
"logicalInterfaceId": "5846ed076522050001db0e12",
"ruleId": "*",
"type": "*",
"typeId": "*",
"instanceId": "*"
},
"variableMappings": {
"someId": "$event.instanceId",
"somevalue": "$event.logicalInterfaceId",
"deviceIntHeader": "'device-version'",
"intValue": "$event.state.version",
"someInt": "$event.state.temperature * 2",
"someString": "$event.ruleId"
}
}
Use action variables to include data from the triggering event in your action resources, for example to include properties from the rule notification in a webhook action. Variables are defined using Mustache syntax. An action can define a maximum of 32 unique variables.
The following features of mustache are supported:
{{myVariable}}{{mySection}}
Hello {{name}}
{{/mySection}}
{{^invertedSection}}
No name specified!
{{/invertedSection}}
{{! Comment}}
You map data from the triggering event to action resource variables using the variableMappings property on your trigger resource. Variable mappings are JSONata expressions.
This allows you to perform more complex operations in a variable mapping than simply copying the value of a property from the notifcation event to the variable. A variable mapping expression can reference properties on the triggering event using the
$event variable.
Consider the rule notification example:
{
"type" : "device",
"typeId" : "TSensor",
"instanceId" : "tsensor",
"logicalInterfaceId": "5846ed076522050001db0e12",
"ruleId" : "5a71991e59080100328710e9",
"ruleCondition": "$state.temperature > 100",
"state" : {
"temperature": 105
},
"timestamp": "2018-01-31T10:29:28Z",
"updated": "2018-01-31T10:29:10Z"
}
An example of variable mappings that reference properties from this rule notification is as follows:
"variableMappings": {
"someId": "$event.instanceId",
"somevalue": "$event.logicalInterfaceId",
"deviceIntHeader": "device-version",
"intValue": "$event.state.temperature",
"someInt": "$event.state.temperature * (9/5) + 32",
"someString": "$event.ruleId"
}
Tip: Note that you can perform arithmetic operations as part of the variable mapping. For example, the variable mapping expression for the someInt variable converts the original temperature property from the
state contained in the rule notification from degrees Celsius to Fahrenheit.