Custom Actions¶

Produce Custom Action Messages¶

You can use Custom Actions to enable communication between two Applications on either the same cluster or across different clusters.

To ensure the Custom Action being sent is handled properly, the app.yaml outputs needs to be declared:

1
2
3

custom_actions:
  outputs:
    - type: custom-action-name

The Custom Action Object in the main.py script supports the following attributes :

Custom Action UI Schemas¶

You can define a UI schema for each Custom Action type your Application produces. This creates an input form in the Kelvin UI's Applications section where users can configure settings specific to this publisher application.

Declare the schemas in the ui_schemas.custom_actions section of your app.yaml, keyed by action type name:

1
2
3
4
5
6
7
8
9

custom_actions:
  outputs:
    - type: send-email
    - type: apply-setpoint

ui_schemas:
  custom_actions:
    send-email: "ui_schemas/send_email.json"
    apply-setpoint: "ui_schemas/apply_setpoint.json"

Each file is a JSON Schema that defines the configuration fields presented to users in the Kelvin UI for this publisher application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Email Publisher Settings",
    "description": "Configuration specific to this publisher application.",
    "type": "object",
    "properties": {
        "from_address": {
            "type": "string",
            "title": "From Address",
            "description": "Email address to send from for this application."
        },
        "default_subject": {
            "type": "string",
            "title": "Default Subject",
            "description": "Default subject line used by this application when sending email actions."
        }
    },
    "required": ["from_address"],
    "additionalProperties": false
}

Example¶

In this example we will create a Producer Application that will;

1. Package the email details into a Custom Action Object
2. Send the Custom Action object directly to the Consumer Application (Executor) for processing.
3. Package the Custom Action object in a Recommendation and publish the "Recommendation with Custom Action" to the Kelvin UI for approval. (Typically, you would choose either direct sending or publishing with a Recommendation—not both.)

Check out the Consume Custom Actions documentation here to see how to receive this Custom Action in a Consumer Application (Executor).

app.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

spec_version: 5.0.0
type: app            # Any app type can handle and/or publish custom actions.

name: hello-app
title: Hello App
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit
version: 1.0.0

custom_actions:
  outputs:
    - type: email

  ...

Publisher Application

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import asyncio
from datetime import timedelta, datetime

from kelvin.application import KelvinApp
from kelvin.krn import KRNAsset
from kelvin.message import Recommendation, CustomAction

app = KelvinApp()

@app.timer(interval=10)
async def publish_data():

    asset = KRNAsset("air-conditioner-1")

    # Direct Custom Action
    action = CustomAction(resource=asset,
    type="email",
    title="Recommendation to reduce speed",
    description="It is recommended that the speed is reduced",
    expiration_date=datetime.now() + timedelta(hours=1),
    payload={
        "recipient": "operations@example.com",
        "subject": "Recommendation to reduce speed",
        "body": "This is the email body",
    })
    await app.publish(action)


    # Or embedded the Custom Action into a Recommendation   
    rec = Recommendation(resource=asset,
    type="Reduce speed",
    actions=[action],
    )
    await app.publish(rec)

app.run()